[Python-checkins] r67019 - in doctools/trunk: CHANGES doc/rest.rst sphinx/environment.py sphinx/texinputs/howto.cls sphinx/texinputs/manual.cls sphinx/texinputs/sphinx.sty sphinx/textwriter.py tests/root/contents.txt tests/root/markup.txt tests/test_build.py
georg.brandl
python-checkins at python.org
Sat Oct 25 17:54:35 CEST 2008
Author: georg.brandl
Date: Sat Oct 25 17:54:34 2008
New Revision: 67019
Log:
Add global citations. #1.
Modified:
doctools/trunk/CHANGES
doctools/trunk/doc/rest.rst
doctools/trunk/sphinx/environment.py
doctools/trunk/sphinx/texinputs/howto.cls
doctools/trunk/sphinx/texinputs/manual.cls
doctools/trunk/sphinx/texinputs/sphinx.sty
doctools/trunk/sphinx/textwriter.py
doctools/trunk/tests/root/contents.txt
doctools/trunk/tests/root/markup.txt
doctools/trunk/tests/test_build.py
Modified: doctools/trunk/CHANGES
==============================================================================
--- doctools/trunk/CHANGES (original)
+++ doctools/trunk/CHANGES Sat Oct 25 17:54:34 2008
@@ -4,6 +4,27 @@
New features added
------------------
+* Markup features:
+
+ - Citations are now global: all citation defined in any file can be
+ referenced from any file. Citations are collected in a bibliography
+ for LaTeX output.
+
+ - 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.
+
+ - Glossary entries are now automatically added to the index.
+
+ - Figures with captions can now be referred to like section titles,
+ using the ``:ref:`` role without an explicit link text.
+
+ - Added ``cmember`` role for consistency.
+
* HTML output and templates:
- Incompatible change: The "root" relation link (top left in the
@@ -22,7 +43,7 @@
can be subclassed to serialize build HTML in a specific format. The
``PickleHTMLBuilder`` is a concrete subclass of it that uses pickle
as serialization implementation.
-
+
- ``JSONHTMLBuilder`` was added as another ``SerializingHTMLBuilder``
subclass that dumps the generated HTML into JSON files for further
processing.
@@ -35,7 +56,7 @@
definition links.
* New and changed config values:
-
+
- Added support for internationalization in generated text with the
``language`` and ``locale_dirs`` config values. Many thanks to
language contributors:
@@ -91,19 +112,6 @@
* Other changes:
- - 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.
-
- - Glossary entries are now automatically added to the index.
-
- - 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
@@ -112,8 +120,6 @@
- In quickstart, if the selected root path already contains a Sphinx
project, complain and abort.
- - Added ``cmember`` role for consistency.
-
Bugs fixed
----------
Modified: doctools/trunk/doc/rest.rst
==============================================================================
--- doctools/trunk/doc/rest.rst (original)
+++ doctools/trunk/doc/rest.rst Sat Oct 25 17:54:34 2008
@@ -240,17 +240,34 @@
Footnotes
---------
-For footnotes, use ``[#]_`` to mark the footnote location, and add the footnote
-body at the bottom of the document after a "Footnotes" rubric heading, like so::
+For footnotes, use ``[#name]_`` to mark the footnote location, and add the
+footnote body at the bottom of the document after a "Footnotes" rubric heading,
+like so::
- Lorem ipsum [#]_ dolor sit amet ... [#]_
+ Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_
.. rubric:: Footnotes
- .. [#] Text of the first footnote.
- .. [#] Text of the second footnote.
+ .. [#f1] Text of the first footnote.
+ .. [#f2] Text of the second footnote.
-You can also explicitly number the footnotes for better context.
+You can also explicitly number the footnotes (``[1]_``) or use auto-numbered
+footnotes without names (``[#]_``).
+
+
+Citations
+---------
+
+Standard reST citations are supported, with the additional feature that they are
+"global", i.e. all citations can be referenced from all files. Use them like
+so::
+
+ Lorem ipsum [Ref]_ dolor sit amet.
+
+ .. [Ref] Book or article reference, URL or whatever.
+
+Citation usage is similar to footnote usage, but with a label that is not
+numeric or begins with ``#``.
Comments
Modified: doctools/trunk/sphinx/environment.py
==============================================================================
--- doctools/trunk/sphinx/environment.py (original)
+++ doctools/trunk/sphinx/environment.py Sat Oct 25 17:54:34 2008
@@ -138,12 +138,27 @@
nodes.doctest_block):
node.replace_self(node.children[0])
+class CitationReferences(Transform):
+ """
+ Handle citation references before the default docutils transform does.
+ """
+ default_priority = 619
+
+ def apply(self):
+ for citnode in self.document.traverse(nodes.citation_reference):
+ cittext = citnode.astext()
+ refnode = addnodes.pending_xref(cittext, reftype='citation',
+ reftarget=cittext)
+ refnode += nodes.Text('[' + cittext + ']')
+ citnode.parent.replace(citnode, refnode)
+
class SphinxStandaloneReader(standalone.Reader):
"""
Add our own transforms.
"""
- transforms = [DefaultSubstitutions, MoveModuleTargets, HandleCodeBlocks]
+ transforms = [CitationReferences, DefaultSubstitutions, MoveModuleTargets,
+ HandleCodeBlocks]
def get_transforms(self):
return standalone.Reader.get_transforms(self) + self.transforms
@@ -259,7 +274,7 @@
self.labels = {} # labelname -> docname, labelid, sectionname
self.anonlabels = {} # labelname -> docname, labelid
self.reftargets = {} # (type, name) -> docname, labelid
- # where type is term, token, option, envvar
+ # where type is term, token, option, envvar, citation
# Other inventories
self.indexentries = {} # docname -> list of
@@ -530,6 +545,7 @@
self.create_title_from(docname, doctree)
self.note_labels_from(docname, doctree)
self.note_indexentries_from(docname, doctree)
+ self.note_citations_from(docname, doctree)
self.build_toc_from(docname, doctree)
# store time of reading, used to find outdated files
@@ -714,6 +730,15 @@
for node in document.traverse(addnodes.index):
entries.extend(node['entries'])
+ def note_citations_from(self, docname, document):
+ for node in document.traverse(nodes.citation):
+ label = node[0].astext()
+ if ('citation', label) in self.reftargets:
+ self.warn(docname, 'duplicate citation %s, ' % label +
+ 'other instance in %s' % self.doc2path(
+ self.reftargets['citation', label][0]), node.line)
+ self.reftargets['citation', label] = (docname, node['ids'][0])
+
def note_toctree(self, docname, toctreenode):
"""Note a TOC tree directive in a document and gather information about
file relations from it."""
@@ -943,7 +968,7 @@
'meth', 'cfunc', 'cmember', 'cdata', 'ctype', 'cmacro'))
def resolve_references(self, doctree, fromdocname, builder):
- reftarget_roles = set(('token', 'term', 'option'))
+ reftarget_roles = set(('token', 'term', 'option', 'citation'))
# add all custom xref types too
reftarget_roles.update(i[0] for i in additional_xref_types.values())
@@ -1009,6 +1034,9 @@
if typ == 'term':
self.warn(fromdocname, 'term not in glossary: %s' % target,
node.line)
+ elif typ == 'citation':
+ self.warn(fromdocname, 'citation not found: %s' % target,
+ node.line)
newnode = contnode
else:
newnode = nodes.reference('', '')
Modified: doctools/trunk/sphinx/texinputs/howto.cls
==============================================================================
--- doctools/trunk/sphinx/texinputs/howto.cls (original)
+++ doctools/trunk/sphinx/texinputs/howto.cls Sat Oct 25 17:54:34 2008
@@ -58,18 +58,6 @@
\vspace{12pt}
}
-% Fix the theindex environment to add an entry to the Table of Contents; this is
-% much nicer than just having to jump to the end of the book and flip around,
-% especially with multiple indexes.
-%
-\let\py at OldTheindex=\theindex
-\renewcommand{\theindex}{
- \clearpage
- \phantomsection
- \py at OldTheindex
- \addcontentsline{toc}{section}{\indexname}
-}
-
\@ifundefined{fancyhf}{
\pagestyle{plain}}{
\pagestyle{normal}} % start this way; change for
Modified: doctools/trunk/sphinx/texinputs/manual.cls
==============================================================================
--- doctools/trunk/sphinx/texinputs/manual.cls (original)
+++ doctools/trunk/sphinx/texinputs/manual.cls Sat Oct 25 17:54:34 2008
@@ -101,15 +101,3 @@
%
\renewcommand*\l at section{\@dottedtocline{1}{1.5em}{2.6em}}
\renewcommand*\l at subsection{\@dottedtocline{2}{4.1em}{3.5em}}
-
-% Fix the theindex environment to add an entry to the Table of Contents; this is
-% much nicer than just having to jump to the end of the book and flip around,
-% especially with multiple indexes.
-%
-\let\py at OldTheindex=\theindex
-\renewcommand{\theindex}{
- \cleardoublepage
- \phantomsection
- \py at OldTheindex
- \addcontentsline{toc}{chapter}{\indexname}
-}
Modified: doctools/trunk/sphinx/texinputs/sphinx.sty
==============================================================================
--- doctools/trunk/sphinx/texinputs/sphinx.sty (original)
+++ doctools/trunk/sphinx/texinputs/sphinx.sty Sat Oct 25 17:54:34 2008
@@ -682,6 +682,26 @@
}
+% Fix the index and bibliography environments to add an entry to the Table of
+% Contents; this is much nicer than just having to jump to the end of the book
+% and flip around, especially with multiple indexes.
+%
+\let\py at OldTheindex=\theindex
+\renewcommand{\theindex}{
+ \cleardoublepage
+ \phantomsection
+ \py at OldTheindex
+ \addcontentsline{toc}{chapter}{\indexname}
+}
+
+\let\py at OldThebibliography=\thebibliography
+\renewcommand{\thebibliography}[1]{
+ \cleardoublepage
+ \phantomsection
+ \py at OldThebibliography{1}
+ \addcontentsline{toc}{chapter}{\bibname}
+}
+
% Include hyperref last.
\RequirePackage[colorlinks,breaklinks,
linkcolor=InnerLinkColor,filecolor=OuterLinkColor,
Modified: doctools/trunk/sphinx/textwriter.py
==============================================================================
--- doctools/trunk/sphinx/textwriter.py (original)
+++ doctools/trunk/sphinx/textwriter.py Sat Oct 25 17:54:34 2008
@@ -252,6 +252,15 @@
def depart_footnote(self, node):
self.end_state(first='[%s] ' % self._footnote)
+ def visit_citation(self, node):
+ if len(node) and isinstance(node[0], nodes.label):
+ self._citlabel = node[0].astext()
+ else:
+ self._citlabel = ''
+ self.new_state(len(self._citlabel) + 3)
+ def depart_citation(self, node):
+ self.end_state(first='[%s] ' % self._citlabel)
+
def visit_label(self, node):
raise nodes.SkipNode
@@ -584,6 +593,10 @@
self.add_text('[%s]' % node.astext())
raise nodes.SkipNode
+ def visit_citation_reference(self, node):
+ self.add_text('[%s]' % node.astext())
+ raise nodes.SkipNode
+
def visit_Text(self, node):
self.add_text(node.astext())
def depart_Text(self, node):
Modified: doctools/trunk/tests/root/contents.txt
==============================================================================
--- doctools/trunk/tests/root/contents.txt (original)
+++ doctools/trunk/tests/root/contents.txt Sat Oct 25 17:54:34 2008
@@ -23,3 +23,8 @@
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
+
+References
+==========
+
+.. [Ref1] Reference target.
Modified: doctools/trunk/tests/root/markup.txt
==============================================================================
--- doctools/trunk/tests/root/markup.txt (original)
+++ doctools/trunk/tests/root/markup.txt Sat Oct 25 17:54:34 2008
@@ -57,6 +57,8 @@
Stuff [#]_
+Reference lookup: [Ref1]_ (defined in another file).
+
.. seealso::
`Google <http://www.google.com>`_
Modified: doctools/trunk/tests/test_build.py
==============================================================================
--- doctools/trunk/tests/test_build.py (original)
+++ doctools/trunk/tests/test_build.py Sat Oct 25 17:54:34 2008
@@ -57,12 +57,16 @@
'markup.html': {
".//meta[@name='author'][@content='Me']": '',
".//meta[@name='keywords'][@content='docs, sphinx']": '',
+ ".//a[@href='contents.html#ref1']": '',
},
'desc.html': {
".//dt[@id='mod.Cls.meth1']": '',
".//dt[@id='errmod.Error']": '',
".//a[@href='#mod.Cls']": '',
},
+ 'contents.html': {
+ ".//td[@class='label']": '[Ref1]',
+ },
}
class NslessParser(ET.XMLParser):
More information about the Python-checkins
mailing list