1. Georg Brandl
  2. sphinx


georg.brandl  committed a83df96

Add ``toctree_only`` feature to LaTeX builder.

  • Participants
  • Parent commits 0ea2d1b
  • Branches default

Comments (0)

Files changed (4)


View file
 * Support for C++ class names (in the style ``Class::Function``) in C function
+* 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

File doc/conf.py

View file
 # 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'

File doc/config.rst

View file
    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
    * *documentclass*: Must be one of ``'manual'`` or ``'howto'``.  Only "manual"
      documents will get appendices.  Also, howtos will have a simpler title
+   * *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

File sphinx/builder.py

View file
-        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),
             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
             docwriter.write(doctree, destination)
-    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):
                 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)
         self.info("resolving references...")