From f5ed3f40853553f822ff397ec28c869087c2d00e Mon Sep 17 00:00:00 2001 From: Russell Keith-Magee Date: Fri, 3 Jul 2009 05:40:46 +0000 Subject: [PATCH] Fixed #10539 -- Updated Sphinx configuration to accommodate 0.6 while retaining compatibility with 0.4 and 0.5. Thanks to Ramiro Morales for the patch. git-svn-id: http://code.djangoproject.com/svn/django/trunk@11162 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/_ext/djangodocs.py | 53 +++++++++++++++++++++++++++---------- docs/_templates/layout.html | 2 +- 2 files changed, 40 insertions(+), 15 deletions(-) diff --git a/docs/_ext/djangodocs.py b/docs/_ext/djangodocs.py index 65a823e10b..af07a84f32 100644 --- a/docs/_ext/djangodocs.py +++ b/docs/_ext/djangodocs.py @@ -6,10 +6,16 @@ import docutils.nodes import docutils.transforms import sphinx import sphinx.addnodes -import sphinx.builder +try: + from sphinx import builders +except ImportError: + import sphinx.builder as builders import sphinx.directives import sphinx.environment -import sphinx.htmlwriter +try: + import sphinx.writers.html as sphinx_htmlwriter +except ImportError: + import sphinx.htmlwriter as sphinx_htmlwriter import sphinx.roles from docutils import nodes @@ -44,7 +50,7 @@ def setup(app): directivename = "django-admin-option", rolename = "djadminopt", indextemplate = "pair: %s; django-admin command-line option", - parse_node = lambda env, sig, signode: sphinx.directives.parse_option_desc(signode, sig), + parse_node = parse_django_adminopt_node, ) app.add_config_value('django_next_version', '0.0', True) app.add_directive('versionadded', parse_version_directive, 1, (1, 1, 1)) @@ -102,7 +108,7 @@ class SuppressBlockquotes(docutils.transforms.Transform): if len(node.children) == 1 and isinstance(node.children[0], self.suppress_blockquote_child_nodes): node.replace_self(node.children[0]) -class DjangoHTMLTranslator(sphinx.htmlwriter.SmartyPantsHTMLTranslator): +class DjangoHTMLTranslator(sphinx_htmlwriter.SmartyPantsHTMLTranslator): """ Django-specific reST to HTML tweaks. """ @@ -125,10 +131,10 @@ class DjangoHTMLTranslator(sphinx.htmlwriter.SmartyPantsHTMLTranslator): # def visit_literal_block(self, node): self.no_smarty += 1 - sphinx.htmlwriter.SmartyPantsHTMLTranslator.visit_literal_block(self, node) - + sphinx_htmlwriter.SmartyPantsHTMLTranslator.visit_literal_block(self, node) + def depart_literal_block(self, node): - sphinx.htmlwriter.SmartyPantsHTMLTranslator.depart_literal_block(self, node) + sphinx_htmlwriter.SmartyPantsHTMLTranslator.depart_literal_block(self, node) self.no_smarty -= 1 # @@ -162,7 +168,7 @@ class DjangoHTMLTranslator(sphinx.htmlwriter.SmartyPantsHTMLTranslator): # Give each section a unique ID -- nice for custom CSS hooks # This is different on docutils 0.5 vs. 0.4... - if hasattr(sphinx.htmlwriter.SmartyPantsHTMLTranslator, 'start_tag_with_title') and sphinx.__version__ == '0.4.2': + if hasattr(sphinx_htmlwriter.SmartyPantsHTMLTranslator, 'start_tag_with_title') and sphinx.__version__ == '0.4.2': def start_tag_with_title(self, node, tagname, **atts): node = { 'classes': node.get('classes', []), @@ -176,7 +182,7 @@ class DjangoHTMLTranslator(sphinx.htmlwriter.SmartyPantsHTMLTranslator): node['ids'] = ['s-' + i for i in old_ids] if sphinx.__version__ != '0.4.2': node['ids'].extend(old_ids) - sphinx.htmlwriter.SmartyPantsHTMLTranslator.visit_section(self, node) + sphinx_htmlwriter.SmartyPantsHTMLTranslator.visit_section(self, node) node['ids'] = old_ids def parse_django_admin_node(env, sig, signode): @@ -186,6 +192,25 @@ def parse_django_admin_node(env, sig, signode): signode += sphinx.addnodes.desc_name(title, title) return sig +def parse_django_adminopt_node(env, sig, signode): + """A copy of sphinx.directives.CmdoptionDesc.parse_signature()""" + from sphinx import addnodes + from sphinx.directives.desc import option_desc_re + count = 0 + firstname = '' + for m in option_desc_re.finditer(sig): + optname, args = m.groups() + if count: + signode += addnodes.desc_addname(', ', ', ') + signode += addnodes.desc_name(optname, optname) + signode += addnodes.desc_addname(args, args) + if not count: + firstname = optname + count += 1 + if not firstname: + raise ValueError + return firstname + def monkeypatch_pickle_builder(): import shutil from os import path @@ -214,12 +239,12 @@ def monkeypatch_pickle_builder(): # copy the environment file from the doctree dir to the output dir # as needed by the web app - shutil.copyfile(path.join(self.doctreedir, sphinx.builder.ENV_PICKLE_FILENAME), - path.join(self.outdir, sphinx.builder.ENV_PICKLE_FILENAME)) + shutil.copyfile(path.join(self.doctreedir, builders.ENV_PICKLE_FILENAME), + path.join(self.outdir, builders.ENV_PICKLE_FILENAME)) # touch 'last build' file, used by the web application to determine # when to reload its environment and clear the cache - open(path.join(self.outdir, sphinx.builder.LAST_BUILD_FILENAME), 'w').close() + open(path.join(self.outdir, builders.LAST_BUILD_FILENAME), 'w').close() + + builders.PickleHTMLBuilder.handle_finish = handle_finish - sphinx.builder.PickleHTMLBuilder.handle_finish = handle_finish - diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html index eb42298ab3..5bf1da6a37 100644 --- a/docs/_templates/layout.html +++ b/docs/_templates/layout.html @@ -1,6 +1,6 @@ {% extends "!layout.html" %} -{%- macro secondnav %} +{%- macro secondnav() %} {%- if prev %} « previous {{ reldelim2 }}