Tweak TOC generation for correct staging

This CL fixes a couple of errors in the generation of YAML TOCs - so now they
will stage properly to the devsite.

In addition, added an example of expandable sections.

BUG=None
R=binji@chromium.org, sbc@chromium.org

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

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@232218 0039d316-1c4b-4281-b951-d872f2087c98

4 files changed, 30 insertions, 5 deletions

diff --git a/native_client_sdk/src/doc/Makefile b/native_client_sdk/src/doc/Makefile
index d9faadf..ad19b59 100644
--- a/native_client_sdk/src/doc/Makefile
+++ b/native_client_sdk/src/doc/Makefile
@@ -192,6 +192,7 @@ devsite-staging:
 	$(SPHINXBUILD) -b devsite -D devsite_foldername=$(USER) -D devsite_production_mode=1 $(ALLSPHINXOPTS) $(BUILDDIR)/devsite-staging
 	rm -rf $(BUILDDIR)/devsite-staging/images
 	cp -r $(BUILDDIR)/devsite-staging/_images $(BUILDDIR)/devsite-staging/images
+	cp _reference_toc.yaml $(BUILDDIR)/devsite-staging/
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/devsite-staging."
 
diff --git a/native_client_sdk/src/doc/README b/native_client_sdk/src/doc/README
index 2d9bf86..da6e2f5 100644
--- a/native_client_sdk/src/doc/README
+++ b/native_client_sdk/src/doc/README
@@ -40,10 +40,13 @@ To emit docs suitable for pushing to production use::
 
   make devsite-prod
 
-Production mode contains devsite-specific templating and non-HTML constructs.
-The ``devsite-staging`` target is exactly the same except that the html pages
-are all rooted under a folder called $USER, which allows each user to stage his
-own copy of the docs.
+Note that "production use" (and the staging target) are closely tied to the
+Google documentation infrastructure, so it will be of very limited use outside
+Google. Links to related documents here can be google.com specific. Production
+mode contains devsite-specific templating and non-HTML constructs. The
+``devsite-staging`` target is exactly the same except that the html pages are
+all rooted under a folder called $USER, which allows each user to stage his own
+copy of the docs.
 
 When building in production mode you can specify the name of the subfolder in
 which the docs are rooted by specifying ``SPHINXOPTS=-Ddevsite_foldername=``.
@@ -51,6 +54,9 @@ For example::
 
   make devsite-prod SPHINXOPTS=-Ddevsite_foldername=pepper_32
 
+See https://sites.google.com/a/google.com/nativeclient/documents/how-to-update-developer-documentation#TOC-Staging-ReStructuredText-output-on-devsite
+for more information on staging.
+
 Local HTTP server to view the docs
 ----------------------------------
 
diff --git a/native_client_sdk/src/doc/_sphinxext/devsite_builder.py b/native_client_sdk/src/doc/_sphinxext/devsite_builder.py
index 58dffb1..df2c1d2 100644
--- a/native_client_sdk/src/doc/_sphinxext/devsite_builder.py
+++ b/native_client_sdk/src/doc/_sphinxext/devsite_builder.py
@@ -412,7 +412,8 @@ def generate_yaml_tree(app, rst_tree, rootpath=None, title=None):
     template_path = None
     toclines.append('- title: "%s"' % title)
     toclines.append('  path: /native-client/${folder}%s' % rootpath)
-    toclines.append('  section:')
+    if rst_tree:
+      toclines.append('  section:')
     indent = 4
 
   def add_tocline(s):
@@ -432,6 +433,9 @@ def generate_yaml_tree(app, rst_tree, rootpath=None, title=None):
       add_tocline('- include: /native-client/${folder}%s/_toc.yaml' % item.path)
       subtrees.append(item)
 
+  # ensure a \n in the end
+  toclines.append('')
+
   if template_path is not None:
     toc = '\n'.join(toclines)
     # When we have a template file, read the template and substitute the
diff --git a/native_client_sdk/src/doc/rest-devsite-examples.rst b/native_client_sdk/src/doc/rest-devsite-examples.rst
index d5ae0d8..eeaf505 100644
--- a/native_client_sdk/src/doc/rest-devsite-examples.rst
+++ b/native_client_sdk/src/doc/rest-devsite-examples.rst
@@ -185,6 +185,20 @@ Sub-sub-subsection heading
 
 It's probably not the best idea to go this far (renders to ``<h5>``).
 
+Expandable sections
+===================
+
+The devsite can render expandable sections when a special ``class`` is applied.
+This can be achieved by specifying the ``rst-class`` immediately before a
+section (or any other element), as follows:
+
+.. rst-class:: expandable
+
+Expandable Section
+------------------
+
+Look, ma! I'm expandable!
+
 Lists
 =====