From 5d272bdd0d1eb765529f986859fef6b85bfcc68d Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 23 Mar 2008 15:07:15 +0000 Subject: [PATCH] Make sphinx compatible with docutils SVN snapshots. --- CHANGES | 6 ++++-- doc/ext/doctest.rst | 2 +- doc/intro.rst | 4 ++-- setup.py | 2 +- sphinx/directives.py | 4 ++-- sphinx/ext/autodoc.py | 4 ++-- sphinx/htmlwriter.py | 26 ++++++++++++++++++++------ sphinx/util/compat.py | 37 +++++++++++++++++++++++++++++++++++++ 8 files changed, 69 insertions(+), 16 deletions(-) create mode 100644 sphinx/util/compat.py diff --git a/CHANGES b/CHANGES index fe7de1ed6..e2330c31e 100644 --- a/CHANGES +++ b/CHANGES @@ -1,5 +1,7 @@ -Changes in trunk -================ +Release 0.1.61798 (Mar 23, 2008) +================================ + +* sphinx: Work with docutils SVN snapshots as well as 0.4. * sphinx.ext.doctest: Make the group in which doctest blocks are placed selectable, and default to ``'default'``. diff --git a/doc/ext/doctest.rst b/doc/ext/doctest.rst index f41efad5c..cfcd0bec0 100644 --- a/doc/ext/doctest.rst +++ b/doc/ext/doctest.rst @@ -77,7 +77,7 @@ names. They will be respected when the test is run, but stripped from presentation output. - .. versionadded:: 0.2 + .. versionadded:: 0.1.61798 Removal of ```` and inline options in presentation output. diff --git a/doc/intro.rst b/doc/intro.rst index 897b8f430..7dabb69fa 100644 --- a/doc/intro.rst +++ b/doc/intro.rst @@ -17,8 +17,8 @@ Prerequisites Sphinx needs at least **Python 2.4** to run. If you like to have source code highlighting support, you must also install the Pygments_ library, which you can -do via setuptools' easy_install. Also, you need docutils version 0.4 (not some -SVN trunk snapshot, because of incompatible API changes). +do via setuptools' easy_install. Sphinx should work with docutils version 0.4 +or some (not broken) SVN trunk snapshot. .. _reStructuredText: http://docutils.sf.net/rst.html .. _Pygments: http://pygments.org diff --git a/setup.py b/setup.py index 210416acc..59063eb92 100644 --- a/setup.py +++ b/setup.py @@ -65,5 +65,5 @@ setup( 'sphinx-quickstart = sphinx.quickstart:main' ] }, - install_requires=['Pygments>=0.8', 'docutils==0.4'] + install_requires=['Pygments>=0.8', 'docutils>=0.4'] ) diff --git a/sphinx/directives.py b/sphinx/directives.py index 950836558..95ac565ee 100644 --- a/sphinx/directives.py +++ b/sphinx/directives.py @@ -17,9 +17,9 @@ from os import path from docutils import nodes from docutils.parsers.rst import directives -from docutils.parsers.rst.directives import admonitions from sphinx import addnodes +from sphinx.util.compat import make_admonition # ------ index markup -------------------------------------------------------------- @@ -446,7 +446,7 @@ directives.register_directive('versionchanged', version_directive) def seealso_directive(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine): - rv = admonitions.make_admonition( + rv = make_admonition( addnodes.seealso, name, ['See also'], options, content, lineno, content_offset, block_text, state, state_machine) return rv diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index 05091e70f..3518c3894 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -140,13 +140,13 @@ def generate_rst(what, name, members, undoc, add_content, indent += ' ' # add docstring content - if what == 'module' and env.config.automodule_skip_lines: + if what == 'module' and env.config.automodule_skip_lines and docstring: docstring = '\n'.join(docstring.splitlines() [env.config.automodule_skip_lines:]) # get the encoding of the docstring module = getattr(todoc, '__module__', None) - if module is not None: + if module is not None and docstring is not None: docstring = docstring.decode(get_module_charset(module)) docstring = prepare_docstring(docstring) diff --git a/sphinx/htmlwriter.py b/sphinx/htmlwriter.py index 1d8df4f2f..b651c8c38 100644 --- a/sphinx/htmlwriter.py +++ b/sphinx/htmlwriter.py @@ -31,8 +31,10 @@ class HTMLWriter(Writer): self.output = visitor.astext() for attr in ('head_prefix', 'stylesheet', 'head', 'body_prefix', 'body_pre_docinfo', 'docinfo', 'body', 'fragment', - 'body_suffix'): - setattr(self, attr, getattr(visitor, attr)) + 'body_suffix', 'meta', 'title', 'subtitle', 'header', + 'footer', 'html_prolog', 'html_head', 'html_title', + 'html_subtitle', 'html_body', ): + setattr(self, attr, getattr(visitor, attr, None)) version_text = { @@ -150,7 +152,7 @@ class HTMLTranslator(BaseTranslator): # overwritten def visit_admonition(self, node, name=''): - self.body.append(self.start_tag_with_title( + self.body.append(self.starttag( node, 'div', CLASS=('admonition ' + name))) if name and name != 'seealso': node.insert(0, nodes.title(name, self.language.labels[name])) @@ -161,8 +163,8 @@ class HTMLTranslator(BaseTranslator): def depart_seealso(self, node): self.depart_admonition(node) - # overwritten - def visit_title(self, node, move_ids=1): + # overwritten (args/kwds due to docutils 0.4/0.5 incompatibility) + def visit_title(self, node, *args, **kwds): # if we have a section we do our own processing in order # to have ids in the hN-tags and not in additional a-tags if isinstance(node.parent, nodes.section): @@ -174,7 +176,7 @@ class HTMLTranslator(BaseTranslator): self.body.append(self.starttag(node, 'h%d' % h_level, '', **attrs)) self.context.append('\n' % h_level) else: - BaseTranslator.visit_title(self, node, move_ids) + BaseTranslator.visit_title(self, node, *args, **kwds) # overwritten def visit_literal_block(self, node): @@ -264,6 +266,18 @@ class HTMLTranslator(BaseTranslator): def depart_module(self, node): pass + # docutils 0.5 compatibility + def visit_note(self, node): + self.visit_admonition(node, 'note') + def depart_note(self, node): + self.depart_admonition(node) + + # docutils 0.5 compatibility + def visit_warning(self, node): + self.visit_admonition(node, 'warning') + def depart_warning(self, node): + self.depart_admonition(node) + # these are only handled specially in the SmartyPantsHTMLTranslator def visit_literal_emphasis(self, node): return self.visit_emphasis(node) diff --git a/sphinx/util/compat.py b/sphinx/util/compat.py new file mode 100644 index 000000000..f7d646b6c --- /dev/null +++ b/sphinx/util/compat.py @@ -0,0 +1,37 @@ +# -*- coding: utf-8 -*- +""" + sphinx.util.compat + ~~~~~~~~~~~~~~~~~~ + + Stuff for docutils compatibility. + + :copyright: 2008 by Georg Brandl. + :license: BSD. +""" + +from docutils import nodes + + +# function missing in 0.5 SVN +def make_admonition(node_class, name, arguments, options, content, lineno, + content_offset, block_text, state, state_machine): + if not content: + error = state_machine.reporter.error( + 'The "%s" admonition is empty; content required.' % (name), + nodes.literal_block(block_text, block_text), line=lineno) + return [error] + text = '\n'.join(content) + admonition_node = node_class(text) + if arguments: + title_text = arguments[0] + textnodes, messages = state.inline_text(title_text, lineno) + admonition_node += nodes.title(title_text, '', *textnodes) + admonition_node += messages + if options.has_key('class'): + classes = options['class'] + else: + classes = ['admonition-' + nodes.make_id(title_text)] + admonition_node['classes'] += classes + state.nested_parse(content, content_offset, admonition_node) + return [admonition_node] +