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

8 files changed, 152 insertions, 115 deletions

diff --git a/native_client_sdk/src/doc/.gitignore b/native_client_sdk/src/doc/.gitignore
index d4e11e5..e35d885 100644
--- a/native_client_sdk/src/doc/.gitignore
+++ b/native_client_sdk/src/doc/.gitignore
@@ -1,2 +1 @@
 _build
-
diff --git a/native_client_sdk/src/doc/Makefile b/native_client_sdk/src/doc/Makefile
index 435b72c..024730d 100644
--- a/native_client_sdk/src/doc/Makefile
+++ b/native_client_sdk/src/doc/Makefile
@@ -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"
diff --git a/native_client_sdk/src/doc/PRESUBMIT.py b/native_client_sdk/src/doc/PRESUBMIT.py
new file mode 100644
index 0000000..22dceb7
--- /dev/null
+++ b/native_client_sdk/src/doc/PRESUBMIT.py
@@ -0,0 +1,33 @@
+# 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)
diff --git a/native_client_sdk/src/doc/README b/native_client_sdk/src/doc/README
index 7d3a40c..14edf8a 100644
--- a/native_client_sdk/src/doc/README
+++ b/native_client_sdk/src/doc/README
@@ -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
diff --git a/native_client_sdk/src/doc/devguide/distributing.rst b/native_client_sdk/src/doc/devguide/distributing.rst
index e17af81..eec8578 100644
--- a/native_client_sdk/src/doc/devguide/distributing.rst
+++ b/native_client_sdk/src/doc/devguide/distributing.rst
@@ -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
diff --git a/native_client_sdk/src/doc/index.rst b/native_client_sdk/src/doc/index.rst
index 663c0b3..cec5c7b 100644
--- a/native_client_sdk/src/doc/index.rst
+++ b/native_client_sdk/src/doc/index.rst
@@ -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
-
diff --git a/native_client_sdk/src/doc/rest-devsite-examples.rst b/native_client_sdk/src/doc/rest-devsite-examples.rst
index afec951..304f972 100644
--- a/native_client_sdk/src/doc/rest-devsite-examples.rst
+++ b/native_client_sdk/src/doc/rest-devsite-examples.rst
@@ -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:
 
diff --git a/native_client_sdk/src/doc/sdk/examples.rst b/native_client_sdk/src/doc/sdk/examples.rst
index c11a5ff..46b3bea 100644
--- a/native_client_sdk/src/doc/sdk/examples.rst
+++ b/native_client_sdk/src/doc/sdk/examples.rst
@@ -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.