[Python-checkins] r62712 - in doctools/trunk: CHANGES doc/conf.py doc/config.rst sphinx/builder.py
georg.brandl
python-checkins at python.org
Sun May 4 23:35:03 CEST 2008
Author: georg.brandl
Date: Sun May 4 23:35:03 2008
New Revision: 62712
Log:
Add ``toctree_only`` feature to LaTeX builder.
Modified:
doctools/trunk/CHANGES
doctools/trunk/doc/conf.py
doctools/trunk/doc/config.rst
doctools/trunk/sphinx/builder.py
Modified: doctools/trunk/CHANGES
==============================================================================
--- doctools/trunk/CHANGES (original)
+++ doctools/trunk/CHANGES Sun May 4 23:35:03 2008
@@ -33,6 +33,10 @@
* 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
----------
Modified: doctools/trunk/doc/conf.py
==============================================================================
--- doctools/trunk/doc/conf.py (original)
+++ doctools/trunk/doc/conf.py Sun May 4 23:35:03 2008
@@ -119,7 +119,7 @@
# 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'
Modified: doctools/trunk/doc/config.rst
==============================================================================
--- doctools/trunk/doc/config.rst (original)
+++ doctools/trunk/doc/config.rst Sun May 4 23:35:03 2008
@@ -293,7 +293,7 @@
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 @@
* *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
Modified: doctools/trunk/sphinx/builder.py
==============================================================================
--- doctools/trunk/sphinx/builder.py (original)
+++ doctools/trunk/sphinx/builder.py Sun May 4 23:35:03 2008
@@ -745,13 +745,17 @@
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 @@
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 @@
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...")
More information about the Python-checkins
mailing list