Fixed #14005 - Removed a few unneeded workarounds in the Sphinx extension. Thanks for the report and patch, Ramiro Morales.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@13447 bcc190cf-cafb-0310-a4f2-bffc1f526a37

docs/_ext/djangodocs.py

@@ -1,9 +1,9 @@
 """
 Sphinx plugins for Django documentation.
 """
+import os
 
-import docutils.nodes
-import docutils.transforms
+from docutils import nodes, transforms
 try:
     import json
 except ImportError:
@@ -14,26 +14,12 @@ except ImportError:
             from django.utils import simplejson as json
         except ImportError:
             json = None
-import os
-import sphinx
-import sphinx.addnodes
-try:
-    from sphinx import builders
-except ImportError:
-    import sphinx.builder as builders
-try:
-    import sphinx.builders.html as builders_html
-except ImportError:
-    builders_html = builders
+
+from sphinx import addnodes, roles
+from sphinx.builders.html import StandaloneHTMLBuilder
+from sphinx.writers.html import SmartyPantsHTMLTranslator
 from sphinx.util.console import bold
-import sphinx.directives
-import sphinx.environment
-try:
-    import sphinx.writers.html as sphinx_htmlwriter
-except ImportError:
-    import sphinx.htmlwriter as sphinx_htmlwriter
-import sphinx.roles
-from docutils import nodes
+
 
 def setup(app):
     app.add_crossref_type(
@@ -74,24 +60,20 @@ def setup(app):
     app.add_transform(SuppressBlockquotes)
     app.add_builder(DjangoStandaloneHTMLBuilder)
 
-    # Monkeypatch PickleHTMLBuilder so that it doesn't die in Sphinx 0.4.2
-    if sphinx.__version__ == '0.4.2':
-        monkeypatch_pickle_builder()
-
 def parse_version_directive(name, arguments, options, content, lineno,
                       content_offset, block_text, state, state_machine):
     env = state.document.settings.env
     is_nextversion = env.config.django_next_version == arguments[0]
     ret = []
-    node = sphinx.addnodes.versionmodified()
+    node = addnodes.versionmodified()
     ret.append(node)
     if not is_nextversion:
         if len(arguments) == 1:
             linktext = 'Please, see the release notes <releases-%s>' % (arguments[0])
             try:
-                xrefs = sphinx.roles.XRefRole()('ref', linktext, linktext, lineno, state) # Sphinx >= 1.0
+                xrefs = roles.XRefRole()('ref', linktext, linktext, lineno, state) # Sphinx >= 1.0
             except:
-                xrefs = sphinx.roles.xfileref_role('ref', linktext, linktext, lineno, state) # Sphinx < 1.0
+                xrefs = roles.xfileref_role('ref', linktext, linktext, lineno, state) # Sphinx < 1.0
             node.extend(xrefs[0])
         node['version'] = arguments[0]
     else:
@@ -106,29 +88,29 @@ def parse_version_directive(name, arguments, options, content, lineno,
     env.note_versionchange(node['type'], node['version'], node, lineno)
     return ret
 
-                
-class SuppressBlockquotes(docutils.transforms.Transform):
+
+class SuppressBlockquotes(transforms.Transform):
     """
     Remove the default blockquotes that encase indented list, tables, etc.
     """
     default_priority = 300
-    
+
     suppress_blockquote_child_nodes = (
-        docutils.nodes.bullet_list, 
-        docutils.nodes.enumerated_list, 
-        docutils.nodes.definition_list,
-        docutils.nodes.literal_block, 
-        docutils.nodes.doctest_block, 
-        docutils.nodes.line_block, 
-        docutils.nodes.table
+        nodes.bullet_list,
+        nodes.enumerated_list,
+        nodes.definition_list,
+        nodes.literal_block,
+        nodes.doctest_block,
+        nodes.line_block,
+        nodes.table
     )
-    
+
     def apply(self):
-        for node in self.document.traverse(docutils.nodes.block_quote):
+        for node in self.document.traverse(nodes.block_quote):
             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(SmartyPantsHTMLTranslator):
     """
     Django-specific reST to HTML tweaks.
     """
@@ -136,42 +118,41 @@ class DjangoHTMLTranslator(sphinx_htmlwriter.SmartyPantsHTMLTranslator):
     # Don't use border=1, which docutils does by default.
     def visit_table(self, node):
         self.body.append(self.starttag(node, 'table', CLASS='docutils'))
-    
+
     # <big>? Really?
     def visit_desc_parameterlist(self, node):
         self.body.append('(')
         self.first_param = 1
-    
+
     def depart_desc_parameterlist(self, node):
         self.body.append(')')
-        pass
-        
+
     #
     # Don't apply smartypants to literal blocks
     #
     def visit_literal_block(self, node):
         self.no_smarty += 1
-        sphinx_htmlwriter.SmartyPantsHTMLTranslator.visit_literal_block(self, node)
+        SmartyPantsHTMLTranslator.visit_literal_block(self, node)
 
     def depart_literal_block(self, node):
-        sphinx_htmlwriter.SmartyPantsHTMLTranslator.depart_literal_block(self, node)
+        SmartyPantsHTMLTranslator.depart_literal_block(self, node)
         self.no_smarty -= 1
-        
+
     #
-    # Turn the "new in version" stuff (versoinadded/versionchanged) into a
+    # Turn the "new in version" stuff (versionadded/versionchanged) into a
     # better callout -- the Sphinx default is just a little span,
     # which is a bit less obvious that I'd like.
     #
     # FIXME: these messages are all hardcoded in English. We need to change
     # that to accomodate other language docs, but I can't work out how to make
-    # that work and I think it'll require Sphinx 0.5 anyway.
+    # that work.
     #
     version_text = {
         'deprecated':       'Deprecated in Django %s',
         'versionchanged':   'Changed in Django %s',
         'versionadded':     'New in Django %s',
     }
-    
+
     def visit_versionmodified(self, node):
         self.body.append(
             self.starttag(node, 'div', CLASS=node['type'])
@@ -181,40 +162,27 @@ class DjangoHTMLTranslator(sphinx_htmlwriter.SmartyPantsHTMLTranslator):
             len(node) and ":" or "."
         )
         self.body.append('<span class="title">%s</span> ' % title)
-    
+
     def depart_versionmodified(self, node):
         self.body.append("</div>\n")
-    
-    # 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':
-        def start_tag_with_title(self, node, tagname, **atts):
-            node = {
-                'classes': node.get('classes', []), 
-                'ids': ['s-%s' % i for i in node.get('ids', [])]
-            }
-            return self.starttag(node, tagname, **atts)
 
-    else:
-        def visit_section(self, node):
-            old_ids = node.get('ids', [])
-            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)
-            node['ids'] = old_ids
+    # Give each section a unique ID -- nice for custom CSS hooks
+    def visit_section(self, node):
+        old_ids = node.get('ids', [])
+        node['ids'] = ['s-' + i for i in old_ids]
+        node['ids'].extend(old_ids)
+        SmartyPantsHTMLTranslator.visit_section(self, node)
+        node['ids'] = old_ids
 
 def parse_django_admin_node(env, sig, signode):
     command = sig.split(' ')[0]
     env._django_curr_admin_command = command
     title = "django-admin.py %s" % sig
-    signode += sphinx.addnodes.desc_name(title, title)
+    signode += 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
     try:
         from sphinx.domains.std import option_desc_re # Sphinx >= 1.0
     except:
@@ -234,44 +202,8 @@ def parse_django_adminopt_node(env, sig, signode):
         raise ValueError
     return firstname
 
-def monkeypatch_pickle_builder():
-    import shutil
-    from os import path
-    try:
-        import cPickle as pickle
-    except ImportError:
-        import pickle
-    
-    def handle_finish(self):
-        # dump the global context
-        outfilename = path.join(self.outdir, 'globalcontext.pickle')
-        f = open(outfilename, 'wb')
-        try:
-            pickle.dump(self.globalcontext, f, 2)
-        finally:
-            f.close()
-
-        self.info(bold('dumping search index...'))
-        self.indexer.prune(self.env.all_docs)
-        f = open(path.join(self.outdir, 'searchindex.pickle'), 'wb')
-        try:
-            self.indexer.dump(f, 'pickle')
-        finally:
-            f.close()
-
-        # copy the environment file from the doctree dir to the output dir
-        # as needed by the web app
-        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, builders.LAST_BUILD_FILENAME), 'w').close()
-
-    builders.PickleHTMLBuilder.handle_finish = handle_finish
-
 
-class DjangoStandaloneHTMLBuilder(builders_html.StandaloneHTMLBuilder):
+class DjangoStandaloneHTMLBuilder(StandaloneHTMLBuilder):
     """
     Subclass to add some extra things we need.
     """

docs/conf.py

@@ -29,7 +29,7 @@ sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), "_ext"))
 extensions = ["djangodocs"]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ["_templates"]
+# templates_path = []
 
 # The suffix of source filenames.
 source_suffix = '.txt'

docs/internals/documentation.txt

@@ -15,6 +15,11 @@ __ http://docutils.sourceforge.net/
 To actually build the documentation locally, you'll currently need to install
 Sphinx -- ``easy_install Sphinx`` should do the trick.
 
+.. note::
+
+    Generation of the Django documentation will work with Sphinx version 0.6
+    or newer, but we recommend going straigh to Sphinx 1.0 or newer.
+
 Then, building the html is easy; just ``make html`` from the ``docs`` directory.
 
 To get started contributing, you'll want to read the `ReStructuredText