Commit 953f4be2 authored by Jannis Leidel's avatar Jannis Leidel
Browse files

[1.2.X] Fixed #14005 - Removed a few unneeded workarounds in the Sphinx... 

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

Backport of r13447 from trunk.



git-svn-id: http://code.djangoproject.com/svn/django/branches/releases/1.2.X@13448 bcc190cf-cafb-0310-a4f2-bffc1f526a37
parent acbf74a7

docs/_ext/djangodocs.py

+42 −110
Original line number Diff line number Diff line 
"""

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:
@@ -107,28 +89,28 @@ def parse_version_directive(name, arguments, options, content, 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.

    """
@@ -144,27 +126,26 @@ class DjangoHTMLTranslator(sphinx_htmlwriter.SmartyPantsHTMLTranslator): 


    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',
@@ -186,35 +167,22 @@ class DjangoHTMLTranslator(sphinx_htmlwriter.SmartyPantsHTMLTranslator): 
        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)

        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

+1 −1
Original line number Diff line number Diff line
@@ -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

+5 −0
Original line number Diff line number Diff line
@@ -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