Add `toctree_only` feature to LaTeX builder.

CHANGES

@@ -33,6 +33,10 @@ New features added
 * Support for C++ class names (in the style ``Class::Function``) in C function
   descriptions.
 
+* Support for a ``toctree_only`` item in items for the ``latex_documents``
+  config value.  This only includes the documents referenced by TOC trees in the
+  output, not the rest of the file containing the directive.
+
 Bugs fixed
 ----------
 

doc/conf.py

@@ -119,7 +119,7 @@ htmlhelp_basename = 'Sphinxdoc'
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, document class [howto/manual]).
 latex_documents = [('contents', 'sphinx.tex', 'Sphinx Documentation',
-                    'Georg Brandl', 'manual')]
+                    'Georg Brandl', 'manual', 1)]
 
 latex_logo = '_static/sphinx.png'
 

doc/config.rst

@@ -293,7 +293,7 @@ These options influence LaTeX output.
 
    This value determines how to group the document tree into LaTeX source files.
    It must be a list of tuples ``(startdocname, targetname, title, author,
-   documentclass)``, where the items are:
+   documentclass, toctree_only)``, where the items are:
 
    * *startdocname*: document name that is the "root" of the LaTeX file.  All
      documents referenced by it in TOC trees will be included in the LaTeX file
@@ -306,6 +306,13 @@ These options influence LaTeX output.
    * *documentclass*: Must be one of ``'manual'`` or ``'howto'``.  Only "manual"
      documents will get appendices.  Also, howtos will have a simpler title
      page.
+   * *toctree_only*: Must be ``True`` or ``False``.  If ``True``, the *startdoc*
+     document itself is not included in the output, only the documents
+     referenced by it via TOC trees.  With this option, you can put extra stuff
+     in the master document that shows up in the HTML, but not the LaTeX output.
+
+   .. versionadded:: 0.3
+      The 6th item ``toctree_only``.  Tuples with 5 items are still accepted.
 
 .. confval:: latex_logo
 

sphinx/builder.py

@@ -745,13 +745,17 @@ class LaTeXBuilder(Builder):
 
         self.init_document_data()
 
-        for docname, targetname, title, author, docclass in self.document_data:
+        for entry in self.document_data:
+            docname, targetname, title, author, docclass = entry[:5]
+            toctree_only = False
+            if len(entry) > 5:
+                toctree_only = entry[5]
             destination = FileOutput(
                 destination_path=path.join(self.outdir, targetname),
                 encoding='utf-8')
             self.info("processing " + targetname + "... ", nonl=1)
-            doctree = self.assemble_doctree(
-                docname, appendices=(docclass == 'manual') and appendices or [])
+            doctree = self.assemble_doctree(docname, toctree_only,
+                appendices=(docclass == 'manual') and appendices or [])
             self.info("writing... ", nonl=1)
             doctree.settings = docsettings
             doctree.settings.author = author
@@ -761,7 +765,7 @@ class LaTeXBuilder(Builder):
             docwriter.write(doctree, destination)
             self.info("done")
 
-    def assemble_doctree(self, indexfile, appendices):
+    def assemble_doctree(self, indexfile, toctree_only, appendices):
         self.docnames = set([indexfile] + appendices)
         self.info(darkgreen(indexfile) + " ", nonl=1)
         def process_tree(docname, tree):
@@ -783,7 +787,17 @@ class LaTeXBuilder(Builder):
                         newnodes.extend(subtree.children)
                 toctreenode.parent.replace(toctreenode, newnodes)
             return tree
-        largetree = process_tree(indexfile, self.env.get_doctree(indexfile))
+        tree = self.env.get_doctree(indexfile)
+        if toctree_only:
+            # extract toctree nodes from the tree and put them in a fresh document
+            new_tree = new_document('<latex output>')
+            new_sect = nodes.section()
+            new_sect += nodes.title('<temp>', '<temp>')
+            new_tree += new_sect
+            for node in tree.traverse(addnodes.toctree):
+                new_sect += node
+            tree = new_tree
+        largetree = process_tree(indexfile, tree)
         largetree.extend(appendices)
         self.info()
         self.info("resolving references...")