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 @@
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXOPTS = -W
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = _build
......@@ -19,7 +19,9 @@ ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
# the i18n builder cannot share the environment and doctrees with the others
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:
@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
To build the docs you will needs sphinx installed (and sphinx-build in your
path), and simply run:
make devsite
make
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:
SPHINXOPTS='-D devsite_production_mode=0'
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.
The builder prints out the value of this setting - make sure it's what you
expect it to be. For example:
$ make devsite
sphinx-build -b devsite -d _build/doctrees . _build/devsite
$ make
sphinx-build -b devsite -d _build/doctrees . _build/devsite
Running Sphinx v1.2b1
loading pickled environment... done
----> 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:
and add the files for each architecture in the relevant subdirectory.
Here is a sample app directory structure:
.. naclcode::
:prettyprint: 0
|-- my_app_directory/
| |-- manifest.json
| |-- my_app.html
| |-- my_module.nmf
| +-- css/
| +-- images/
| +-- scripts/
| |-- **_platform_specific/**
| | |-- x86-64/
| | | |-- my_module_x86_64.nexe
| | |-- x86-32/
| | | |-- my_module_x86_32.nexe
| | |-- arm/
| | | |-- my_module_arm.nexe
| | |-- all/
| | | |-- my_module_x86_64.nexe
| | | |-- my_module_x86_64.nexe
| | | |-- my_module_x86_32.nexe
:prettyprint: 0
|-- my_app_directory/
| |-- manifest.json
| |-- my_app.html
| |-- my_module.nmf
| +-- css/
| +-- images/
| +-- scripts/
| |-- **_platform_specific/**
| | |-- x86-64/
| | | |-- my_module_x86_64.nexe
| | |-- x86-32/
| | | |-- my_module_x86_32.nexe
| | |-- arm/
| | | |-- my_module_arm.nexe
| | |-- all/
| | | |-- my_module_x86_64.nexe
| | | |-- my_module_x86_64.nexe
| | | |-- my_module_x86_32.nexe
Please note a few important points about the app directory structure:
* The architecture-specific subdirectories:
......@@ -213,47 +213,47 @@ Here is how to use this feature:
Here is a sample ``manifest.json`` file:
.. naclcode::
:prettyprint: 0
{
"name": "My Reminder App",
"description": "A reminder app that syncs across Chrome browsers.",
"manifest_version": 2,
"minimum_chrome_version": "28",
"offline_enabled": true,
"version": "0.3",
"permissions": [
{"fileSystem": ["write"]},
"alarms",
"storage"
],
"app": {
"background": {
"scripts": ["scripts/background.js"]
}
},
"icons": {
"16": "images/icon-16x16.png",
"128": "images/icon-128x128.png"
},
**"platforms": [
{
"nacl_arch": "x86-64",
"sub_package_path": "_platform_specific/x86-64/"
},
{
"nacl_arch": "x86-32",
"sub_package_path": "_platform_specific/x86-32/"
},
{
"nacl_arch": "arm",
"sub_package_path": "_platform_specific/arm/"
},
{
"sub_package_path": "_platform_specific/all/"
}
]**
}
:prettyprint: 0
{
"name": "My Reminder App",
"description": "A reminder app that syncs across Chrome browsers.",
"manifest_version": 2,
"minimum_chrome_version": "28",
"offline_enabled": true,
"version": "0.3",
"permissions": [
{"fileSystem": ["write"]},
"alarms",
"storage"
],
"app": {
"background": {
"scripts": ["scripts/background.js"]
}
},
"icons": {
"16": "images/icon-16x16.png",
"128": "images/icon-128x128.png"
},
**"platforms": [
{
"nacl_arch": "x86-64",
"sub_package_path": "_platform_specific/x86-64/"
},
{
"nacl_arch": "x86-32",
"sub_package_path": "_platform_specific/x86-32/"
},
{
"nacl_arch": "arm",
"sub_package_path": "_platform_specific/arm/"
},
{
"sub_package_path": "_platform_specific/all/"
}
]**
}
Note the last entry in the CWS manifest file above, which specifies a
``sub_package_path`` without a corresponding ``nacl_arch``. This entry
......@@ -294,10 +294,11 @@ Additional considerations for a packaged application
example:
.. naclcode::
:prettyprint: 0
"launch": {
"web_url": "http://mail.google.com/mail/"
}
"launch": {
"web_url": "http://mail.google.com/mail/"
}
* If you want to write local data using the Pepper
`FileIO </native-client/peppercpp/classpp_1_1_file_i_o>`_
......@@ -394,11 +395,11 @@ Additional considerations for a hosted application
example:
.. naclcode::
:prettyprint: 0
:prettyprint: 0
"launch": {
"web_url": "http://mail.google.com/mail/"
}
"launch": {
"web_url": "http://mail.google.com/mail/"
}
* If you want to write local data using the Pepper
`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
MIME type:
.. naclcode::
:prettyprint: 0
{
"name": "My Native Client Spreadsheet Viewer",
"version": "0.1",
"description": "Open spreadsheets right in your browser.",
**"nacl_modules": [{
"path": "SpreadsheetViewer.nmf",
"mime_type": "application/vnd.oasis.opendocument.spreadsheet"
}]**
}
:prettyprint: 0
{
"name": "My Native Client Spreadsheet Viewer",
"version": "0.1",
"description": "Open spreadsheets right in your browser.",
**"nacl_modules": [{
"path": "SpreadsheetViewer.nmf",
"mime_type": "application/vnd.oasis.opendocument.spreadsheet"
}]**
}
The value of "path" is the location of a Native Client manifest file (.nmf)
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
example shows an extension with two .nmf files that handle three MIME types.
.. naclcode::
:prettyprint: 0
{
"name": "My Native Client Spreadsheet and Document Viewer",
"version": "0.1",
"description": "Open spreadsheets and documents right in your browser.",
"nacl_modules": [{
:prettyprint: 0
{
"name": "My Native Client Spreadsheet and Document Viewer",
"version": "0.1",
"description": "Open spreadsheets and documents right in your browser.",
"nacl_modules": [{
"path": "SpreadsheetViewer.nmf",
"mime_type": "application/vnd.oasis.opendocument.spreadsheet"
},
{
"path": "SpreadsheetViewer.nmf",
"mime_type": "application/vnd.oasis.opendocument.spreadsheet"
},
{
"path": "SpreadsheetViewer.nmf",
"mime_type": "application/vnd.oasis.opendocument.spreadsheet-template"
},
{
"path": "DocumentViewer.nmf",
"mime_type": "application/vnd.oasis.opendocument.text"
}]
}
"mime_type": "application/vnd.oasis.opendocument.spreadsheet-template"
},
{
"path": "DocumentViewer.nmf",
"mime_type": "application/vnd.oasis.opendocument.text"
}]
}
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
......
native_client_sdk/src/doc/index.rst
View file @ 0fcfaab0
......@@ -18,10 +18,12 @@ Contents:
devguide/devcycle/building.rst
devguide/devcycle/running.rst
devguide/devcycle/debugging.rst
devguide/coding/3D-graphics.rst
devguide/coding/audio.rst
devguide/coding/application-structure.rst
devguide/coding/FileIO.rst
devguide/coding/message-system.rst
devguide/coding/progress-events.rst
devguide/distributing.rst
community/application-gallery.rst
peppercpp/index.rst
native_client_sdk/src/doc/rest-devsite-examples.rst
View file @ 0fcfaab0
......@@ -109,12 +109,12 @@ without coloring:
.. naclcode::
#include <iostream>
#include <iostream>
int main() {
std::cout << "Hello world\n";
return 0;
}
int main() {
std::cout << "Hello world\n";
return 0;
}
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>`.
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
use the SDK toolchain itself, see :doc:`Building Native Client Modules
<devcycle/building>`.
<../devguide/devcycle/building>`.
Run the SDK examples
--------------------
......@@ -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.
The most common commands you will use to debug are ``continue``, ``step``,
``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.
......
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