Skip to content

GitLab

T
tangled
Commit 0fcfaab0 authored by sbc@chromium.org's avatar sbc@chromium.org
Browse files
Options

Minor cleanups for SDK devsite docs. 

Add -W to SHPINXOPTS to make warnings into error.

Add presubmit check that makes sure sphinx is happy
with the content.

Use 2 spaces to indent code.

Add a missing document.

Fix document links in examples.rst.

Use 'out' for build product data to be constent with
chrome and native_client.

Add 'all' target so that 'make' on its own will work
(I'm lazy)

R=binji@chromium.org, eliben@chromium.org

Review URL: https://codereview.chromium.org/23531031

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@221806 0039d316-1c4b-4281-b951-d872f2087c98
parent 191dbef8
Hide whitespace changes
Inline Side-by-side
Showing with 152 additions and 115 deletions
native_client_sdk/src/doc/Makefile
View file @ 0fcfaab0
...@@ -2,7 +2,7 @@ ...@@ -2,7 +2,7 @@
# #
# You can set these variables from the command line. # You can set these variables from the command line.
SPHINXOPTS = SPHINXOPTS = -W
SPHINXBUILD = sphinx-build SPHINXBUILD = sphinx-build
PAPER = PAPER =
BUILDDIR = _build BUILDDIR = _build
...@@ -19,7 +19,9 @@ ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . ...@@ -19,7 +19,9 @@ ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
# the i18n builder cannot share the environment and doctrees with the others # the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext all
all: devsite
help: help:
@echo "Please use \`make <target>' where <target> is one of" @echo "Please use \`make <target>' where <target> is one of"
......
native_client_sdk/src/doc/PRESUBMIT.py 0 → 100644
View file @ 0fcfaab0
# Copyright (c) 2012 The Chromium Authors. All rights reserved.
# Use of this source code is governed by a BSD-style license that can be
# found in the LICENSE file.
import subprocess
def _CheckSphinxBuild(input_api, output_api):
"""Check that the docs are buildable without any warnings.
This check runs sphinx-build with -W so that warning are errors.
"""
try:
subprocess.check_output(['make', 'SPHINXOPTS=-Wa'])
except subprocess.CalledProcessError as e:
return [output_api.PresubmitPromptError('sphinx_build failed:\n' +
e.output)]
return []
def CommonChecks(input_api, output_api):
output = []
output.extend(_CheckSphinxBuild(input_api, output_api))
return output
def CheckChangeOnUpload(input_api, output_api):
return CommonChecks(input_api, output_api)
def CheckChangeOnCommit(input_api, output_api):
return CommonChecks(input_api, output_api)
native_client_sdk/src/doc/README
View file @ 0fcfaab0
...@@ -23,25 +23,25 @@ How to build ...@@ -23,25 +23,25 @@ How to build
To build the docs you will needs sphinx installed (and sphinx-build in your To build the docs you will needs sphinx installed (and sphinx-build in your
path), and simply run: path), and simply run:
make devsite make
To rebuild all the pages always, add 'SPHINXOPTS=-a', e.g.: To rebuild all the pages always, add 'SPHINXOPTS=-a', e.g.:
make SPHINXOPTS=-a devsite make SPHINXOPTS=-a
To emit local-testing mode, instead of production mode, add: To emit local-testing mode, instead of production mode, add:
SPHINXOPTS='-D devsite_production_mode=0' SPHINXOPTS='-D devsite_production_mode=0'
e.g.: e.g.:
make SPHINXOPTS='-D devsite_production_mode=0' devsite make SPHINXOPTS='-D devsite_production_mode=0'
Production mode contains devsite-specific templating and non-HTML constructs. Production mode contains devsite-specific templating and non-HTML constructs.
The builder prints out the value of this setting - make sure it's what you The builder prints out the value of this setting - make sure it's what you
expect it to be. For example: expect it to be. For example:
$ make devsite $ make
sphinx-build -b devsite -d _build/doctrees . _build/devsite sphinx-build -b devsite -d _build/doctrees . _build/devsite
Running Sphinx v1.2b1 Running Sphinx v1.2b1
loading pickled environment... done loading pickled environment... done
----> Devsite builder with production mode = 1 ----> Devsite builder with production mode = 1
......
native_client_sdk/src/doc/devguide/distributing.rst
View file @ 0fcfaab0
...@@ -145,29 +145,29 @@ Here is how to use this feature: ...@@ -145,29 +145,29 @@ Here is how to use this feature:
and add the files for each architecture in the relevant subdirectory. and add the files for each architecture in the relevant subdirectory.
Here is a sample app directory structure: Here is a sample app directory structure:
.. naclcode:: .. naclcode::
:prettyprint: 0 :prettyprint: 0
|-- my_app_directory/ |-- my_app_directory/
| |-- manifest.json | |-- manifest.json
| |-- my_app.html | |-- my_app.html
| |-- my_module.nmf | |-- my_module.nmf
| +-- css/ | +-- css/
| +-- images/ | +-- images/
| +-- scripts/ | +-- scripts/
| |-- **_platform_specific/** | |-- **_platform_specific/**
| | |-- x86-64/ | | |-- x86-64/
| | | |-- my_module_x86_64.nexe | | | |-- my_module_x86_64.nexe
| | |-- x86-32/ | | |-- x86-32/
| | | |-- my_module_x86_32.nexe | | | |-- my_module_x86_32.nexe
| | |-- arm/ | | |-- arm/
| | | |-- my_module_arm.nexe | | | |-- my_module_arm.nexe
| | |-- all/ | | |-- all/
| | | |-- my_module_x86_64.nexe | | | |-- my_module_x86_64.nexe
| | | |-- my_module_x86_64.nexe | | | |-- my_module_x86_64.nexe
| | | |-- my_module_x86_32.nexe | | | |-- my_module_x86_32.nexe
Please note a few important points about the app directory structure: Please note a few important points about the app directory structure:
* The architecture-specific subdirectories: * The architecture-specific subdirectories:
...@@ -213,47 +213,47 @@ Here is how to use this feature: ...@@ -213,47 +213,47 @@ Here is how to use this feature:
Here is a sample ``manifest.json`` file: Here is a sample ``manifest.json`` file:
.. naclcode:: .. naclcode::
:prettyprint: 0 :prettyprint: 0
{ {
"name": "My Reminder App", "name": "My Reminder App",
"description": "A reminder app that syncs across Chrome browsers.", "description": "A reminder app that syncs across Chrome browsers.",
"manifest_version": 2, "manifest_version": 2,
"minimum_chrome_version": "28", "minimum_chrome_version": "28",
"offline_enabled": true, "offline_enabled": true,
"version": "0.3", "version": "0.3",
"permissions": [ "permissions": [
{"fileSystem": ["write"]}, {"fileSystem": ["write"]},
"alarms", "alarms",
"storage" "storage"
], ],
"app": { "app": {
"background": { "background": {
"scripts": ["scripts/background.js"] "scripts": ["scripts/background.js"]
} }
}, },
"icons": { "icons": {
"16": "images/icon-16x16.png", "16": "images/icon-16x16.png",
"128": "images/icon-128x128.png" "128": "images/icon-128x128.png"
}, },
**"platforms": [ **"platforms": [
{ {
"nacl_arch": "x86-64", "nacl_arch": "x86-64",
"sub_package_path": "_platform_specific/x86-64/" "sub_package_path": "_platform_specific/x86-64/"
}, },
{ {
"nacl_arch": "x86-32", "nacl_arch": "x86-32",
"sub_package_path": "_platform_specific/x86-32/" "sub_package_path": "_platform_specific/x86-32/"
}, },
{ {
"nacl_arch": "arm", "nacl_arch": "arm",
"sub_package_path": "_platform_specific/arm/" "sub_package_path": "_platform_specific/arm/"
}, },
{ {
"sub_package_path": "_platform_specific/all/" "sub_package_path": "_platform_specific/all/"
} }
]** ]**
} }
Note the last entry in the CWS manifest file above, which specifies a Note the last entry in the CWS manifest file above, which specifies a
``sub_package_path`` without a corresponding ``nacl_arch``. This entry ``sub_package_path`` without a corresponding ``nacl_arch``. This entry
...@@ -294,10 +294,11 @@ Additional considerations for a packaged application ...@@ -294,10 +294,11 @@ Additional considerations for a packaged application
example: example:
.. naclcode:: .. naclcode::
:prettyprint: 0
"launch": { "launch": {
"web_url": "http://mail.google.com/mail/" "web_url": "http://mail.google.com/mail/"
} }
* If you want to write local data using the Pepper * If you want to write local data using the Pepper
`FileIO </native-client/peppercpp/classpp_1_1_file_i_o>`_ `FileIO </native-client/peppercpp/classpp_1_1_file_i_o>`_
...@@ -394,11 +395,11 @@ Additional considerations for a hosted application ...@@ -394,11 +395,11 @@ Additional considerations for a hosted application
example: example:
.. naclcode:: .. naclcode::
:prettyprint: 0 :prettyprint: 0
"launch": { "launch": {
"web_url": "http://mail.google.com/mail/" "web_url": "http://mail.google.com/mail/"
} }
* If you want to write local data using the Pepper * If you want to write local data using the Pepper
`FileIO </native-client/peppercpp/classpp_1_1_file_i_o>`_ `FileIO </native-client/peppercpp/classpp_1_1_file_i_o>`_
...@@ -426,17 +427,17 @@ a Native Client module as the content handler for the OpenOffice spreadsheet ...@@ -426,17 +427,17 @@ a Native Client module as the content handler for the OpenOffice spreadsheet
MIME type: MIME type:
.. naclcode:: .. naclcode::
:prettyprint: 0 :prettyprint: 0
{ {
"name": "My Native Client Spreadsheet Viewer", "name": "My Native Client Spreadsheet Viewer",
"version": "0.1", "version": "0.1",
"description": "Open spreadsheets right in your browser.", "description": "Open spreadsheets right in your browser.",
**"nacl_modules": [{ **"nacl_modules": [{
"path": "SpreadsheetViewer.nmf", "path": "SpreadsheetViewer.nmf",
"mime_type": "application/vnd.oasis.opendocument.spreadsheet" "mime_type": "application/vnd.oasis.opendocument.spreadsheet"
}]** }]**
} }
The value of "path" is the location of a Native Client manifest file (.nmf) The value of "path" is the location of a Native Client manifest file (.nmf)
within the application directory. For more information on Native Client within the application directory. For more information on Native Client
...@@ -449,25 +450,25 @@ file, but a single .nmf file might handle multiple MIME types. The following ...@@ -449,25 +450,25 @@ file, but a single .nmf file might handle multiple MIME types. The following
example shows an extension with two .nmf files that handle three MIME types. example shows an extension with two .nmf files that handle three MIME types.
.. naclcode:: .. naclcode::
:prettyprint: 0 :prettyprint: 0
{ {
"name": "My Native Client Spreadsheet and Document Viewer", "name": "My Native Client Spreadsheet and Document Viewer",
"version": "0.1", "version": "0.1",
"description": "Open spreadsheets and documents right in your browser.", "description": "Open spreadsheets and documents right in your browser.",
"nacl_modules": [{ "nacl_modules": [{
"path": "SpreadsheetViewer.nmf",
"mime_type": "application/vnd.oasis.opendocument.spreadsheet"
},
{
"path": "SpreadsheetViewer.nmf", "path": "SpreadsheetViewer.nmf",
"mime_type": "application/vnd.oasis.opendocument.spreadsheet" "mime_type": "application/vnd.oasis.opendocument.spreadsheet-template"
}, },
{ {
"path": "SpreadsheetViewer.nmf", "path": "DocumentViewer.nmf",
"mime_type": "application/vnd.oasis.opendocument.spreadsheet-template" "mime_type": "application/vnd.oasis.opendocument.text"
}, }]
{ }
"path": "DocumentViewer.nmf",
"mime_type": "application/vnd.oasis.opendocument.text"
}]
}
The ``nacl_modules`` attribute is optional---specify this attribute only if The ``nacl_modules`` attribute is optional---specify this attribute only if
you want Chrome to use a Native Client module to display a particular type of you want Chrome to use a Native Client module to display a particular type of
......
native_client_sdk/src/doc/index.rst
View file @ 0fcfaab0
...@@ -18,10 +18,12 @@ Contents: ...@@ -18,10 +18,12 @@ Contents:
devguide/devcycle/building.rst devguide/devcycle/building.rst
devguide/devcycle/running.rst devguide/devcycle/running.rst
devguide/devcycle/debugging.rst devguide/devcycle/debugging.rst
devguide/coding/3D-graphics.rst
devguide/coding/audio.rst
devguide/coding/application-structure.rst devguide/coding/application-structure.rst
devguide/coding/FileIO.rst
devguide/coding/message-system.rst devguide/coding/message-system.rst
devguide/coding/progress-events.rst devguide/coding/progress-events.rst
devguide/distributing.rst devguide/distributing.rst
community/application-gallery.rst community/application-gallery.rst
peppercpp/index.rst peppercpp/index.rst
native_client_sdk/src/doc/rest-devsite-examples.rst
View file @ 0fcfaab0
...@@ -109,12 +109,12 @@ without coloring: ...@@ -109,12 +109,12 @@ without coloring:
.. naclcode:: .. naclcode::
#include <iostream> #include <iostream>
int main() { int main() {
std::cout << "Hello world\n"; std::cout << "Hello world\n";
return 0; return 0;
} }
For some code (like shell samples), we want to disable pretty-printing: For some code (like shell samples), we want to disable pretty-printing:
......
native_client_sdk/src/doc/sdk/examples.rst
View file @ 0fcfaab0
...@@ -152,7 +152,7 @@ Overview <../overview>`. ...@@ -152,7 +152,7 @@ Overview <../overview>`.
For details on how to use ``make``, see the `GNU 'make' Manual For details on how to use ``make``, see the `GNU 'make' Manual
<http://www.gnu.org/software/make/manual/make.html>`_. For details on how to <http://www.gnu.org/software/make/manual/make.html>`_. For details on how to
use the SDK toolchain itself, see :doc:`Building Native Client Modules use the SDK toolchain itself, see :doc:`Building Native Client Modules
<devcycle/building>`. <../devguide/devcycle/building>`.
Run the SDK examples Run the SDK examples
-------------------- --------------------
...@@ -241,7 +241,7 @@ Chrome is listening on. GDB will respond:: ...@@ -241,7 +241,7 @@ Chrome is listening on. GDB will respond::
At this point, you can use the standard GDB commands to debug your NaCl module. At this point, you can use the standard GDB commands to debug your NaCl module.
The most common commands you will use to debug are ``continue``, ``step``, The most common commands you will use to debug are ``continue``, ``step``,
``next``, ``break`` and ``backtrace``. See :doc:`Debugging ``next``, ``break`` and ``backtrace``. See :doc:`Debugging
<devcycle/debugging>` for more information about debugging a Native Client <../devguide/devcycle/debugging>` for more information about debugging a Native Client
application. application.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment