[Python-checkins] r66594 - in doctools/trunk: CHANGES doc/concepts.rst sphinx/builder.py sphinx/latexwriter.py

Wed Sep 24 18:13:36 CEST 2008

Author: georg.brandl
Date: Wed Sep 24 18:13:36 2008
New Revision: 66594
Log:
#18: put footnotes at the correct location in the LaTeX writer.
Modified:
 doctools/trunk/CHANGES
 doctools/trunk/doc/concepts.rst
 doctools/trunk/sphinx/builder.py
 doctools/trunk/sphinx/latexwriter.py
Modified: doctools/trunk/CHANGES
==============================================================================

--- doctools/trunk/CHANGES	(original)
+++ doctools/trunk/CHANGES	Wed Sep 24 18:13:36 2008
@@ -85,12 +85,11 @@
 ``build-finished``.
 
 * Other changes:
- 
- - Added a distutils command `build_sphinx`: When Sphinx is installed,
- you can call ``python setup.py build_sphinx`` for projects that have
- Sphinx documentation, which will build the docs and place them in
- the standard distutils build directory.
 
+ - Footnotes are now properly handled in the LaTeX builder: they appear
+ at the location of the footnote reference in text, not at the end of
+ a section. Thanks to Andrew McNamara for the initial patch.
+ 
 - "System Message" warnings are now automatically removed from the
 built documentation, and only written to stderr. If you want the
 old behavior, set the new config value ``keep_warnings`` to True.
@@ -100,6 +99,11 @@
 - Figures with captions can now be referred to like section titles,
 using the ``:ref:`` role without an explicit link text.
 
+ - Added a distutils command `build_sphinx`: When Sphinx is installed,
+ you can call ``python setup.py build_sphinx`` for projects that have
+ Sphinx documentation, which will build the docs and place them in
+ the standard distutils build directory.
+
 - In quickstart, if the selected root path already contains a Sphinx
 project, complain and abort.
 
Modified: doctools/trunk/doc/concepts.rst
==============================================================================
--- doctools/trunk/doc/concepts.rst	(original)
+++ doctools/trunk/doc/concepts.rst	Wed Sep 24 18:13:36 2008
@@ -129,6 +129,11 @@
 documents or document-containing directories with such names. (Using ``_`` as
 a prefix for a custom template directory is fine.)
 
+.. toctree::
+
+ x
+
+note [#]_.
 
 .. rubric:: Footnotes
 
@@ -142,3 +147,5 @@
 constructs ``*``, ``?``, ``[...]`` and ``[!...]`` with the feature that
 these all don't match slashes. A double star ``**`` can be used to match
 any sequence of characters *including* slashes.
+
+.. [#] 3rd note.
Modified: doctools/trunk/sphinx/builder.py
==============================================================================
--- doctools/trunk/sphinx/builder.py	(original)
+++ doctools/trunk/sphinx/builder.py	Wed Sep 24 18:13:36 2008
@@ -1019,8 +1019,9 @@
 self.warn('%s: toctree contains ref to nonexisting file %r' %
 (docname, includefile))
 else:
- newnodes.append(addnodes.start_of_file())
- newnodes.extend(subtree.children)
+ sof = addnodes.start_of_file()
+ sof.children = subtree.children
+ newnodes.append(sof)
 toctreenode.parent.replace(toctreenode, newnodes)
 return tree
 tree = self.env.get_doctree(indexfile)
@@ -1046,7 +1047,7 @@
 newnodes = [nodes.emphasis(sectname, sectname)]
 for subdir, title in self.titles:
 if docname.startswith(subdir):
- newnodes.append(nodes.Text(' (in ', ' (in '))
+ newnodes.append(nodes.Text(_(' (in '), _(' (in ')))
 newnodes.append(nodes.emphasis(title, title))
 newnodes.append(nodes.Text(')', ')'))
 break
Modified: doctools/trunk/sphinx/latexwriter.py
==============================================================================
--- doctools/trunk/sphinx/latexwriter.py	(original)
+++ doctools/trunk/sphinx/latexwriter.py	Wed Sep 24 18:13:36 2008
@@ -195,6 +195,7 @@
 self.highlightlang = builder.config.highlight_language
 self.highlightlinenothreshold = sys.maxint
 self.written_ids = set()
+ self.footnotestack = []
 if self.elements['docclass'] == 'manual':
 if builder.config.latex_use_parts:
 self.top_sectionlevel = 0
@@ -216,6 +217,7 @@
 u''.join(self.body) + FOOTER % self.elements)
 
 def visit_document(self, node):
+ self.footnotestack.append(self.collect_footnotes(node))
 if self.first_document == 1:
 # the first document is all the regular content ...
 self.body.append(BEGIN_DOC % self.elements)
@@ -244,7 +246,28 @@
 # This marks the begin of a new file; therefore the current module and
 # class must be reset
 self.body.append('\n\\resetcurrentobjects\n')
- raise nodes.SkipNode
+ # and also, new footnotes
+ self.footnotestack.append(self.collect_footnotes(node))
+
+ def collect_footnotes(self, node):
+ fnotes = {}
+ def footnotes_under(n):
+ if isinstance(n, nodes.footnote):
+ yield n
+ else:
+ for c in n.children:
+ if isinstance(c, addnodes.start_of_file):
+ continue
+ for k in footnotes_under(c):
+ yield k
+ for fn in footnotes_under(node):
+ num = fn.children[0].astext().strip()
+ fnotes[num] = fn
+ fn.parent.remove(fn)
+ return fnotes
+
+ def depart_start_of_file(self, node):
+ self.footnotestack.pop()
 
 def visit_highlightlang(self, node):
 self.highlightlang = node['lang']
@@ -478,11 +501,9 @@
 self.body.append(self.context.pop())
 
 def visit_footnote(self, node):
- # XXX not optimal, footnotes are at section end
- num = node.children[0].astext().strip()
- self.body.append('\\footnotetext[%s]{' % num)
+ pass
 def depart_footnote(self, node):
- self.body.append('}')
+ pass
 
 def visit_label(self, node):
 if isinstance(node.parent, nodes.citation):
@@ -918,8 +939,16 @@
 raise nodes.SkipNode
 
 def visit_footnote_reference(self, node):
- self.body.append('\\footnotemark[%s]' % node.astext())
- raise nodes.SkipNode
+ num = node.astext().strip()
+ try:
+ fn = self.footnotestack[-1][num]
+ except (KeyError, IndexError):
+ raise nodes.SkipNode
+ self.body.append('\\footnote{')
+ fn.walkabout(self)
+ raise nodes.SkipChildren
+ def depart_footnote_reference(self, node):
+ self.body.append('}')
 
 def visit_literal_block(self, node):
 self.verbatim = ''
