Commit d7a60868 authored by Tim Graham's avatar Tim Graham
Browse files

[1.9.x] Fixed #23868 -- Added support for non-unique django-admin-options in docs. 

Also documented missing short command line options to fix #24134. This bumps
the minimum sphinx version required to build the docs to 1.3.4.

Thanks Simon Charette for review.

Backport of e519aab4 from master
parent 0495f44b

docs/_ext/djangodocs.py

+4 −37
Original line number Diff line number Diff line
@@ -9,6 +9,7 @@ from docutils import nodes 
from docutils.parsers.rst import directives

from sphinx import __version__ as sphinx_ver, addnodes

from sphinx.builders.html import StandaloneHTMLBuilder

from sphinx.domains.std import Cmdoption

from sphinx.util.compat import Directive

from sphinx.util.console import bold

from sphinx.util.nodes import set_source_info
@@ -46,12 +47,7 @@ def setup(app): 
        indextemplate="pair: %s; django-admin command",

        parse_node=parse_django_admin_node,

    )

    app.add_description_unit(

        directivename="django-admin-option",

        rolename="djadminopt",

        indextemplate="pair: %s; django-admin command-line option",

        parse_node=parse_django_adminopt_node,

    )

    app.add_directive('django-admin-option', Cmdoption)

    app.add_config_value('django_next_version', '0.0', True)

    app.add_directive('versionadded', VersionDirective)

    app.add_directive('versionchanged', VersionDirective)
@@ -306,39 +302,10 @@ class DjangoHTMLTranslator(SmartyPantsHTMLTranslator): 


def parse_django_admin_node(env, sig, signode):

    command = sig.split(' ')[0]

    env._django_curr_admin_command = command

    env.ref_context['std:program'] = command

    title = "django-admin %s" % sig

    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.domains.std 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 count:

        for m in simple_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

    return command





class DjangoStandaloneHTMLBuilder(StandaloneHTMLBuilder):

docs/conf.py

+1 −1
Original line number Diff line number Diff line
@@ -27,7 +27,7 @@ sys.path.append(abspath(join(dirname(__file__), "_ext"))) 
# -- General configuration -----------------------------------------------------



# If your documentation needs a minimal Sphinx version, state it here.

needs_sphinx = '1.0'

needs_sphinx = '1.3'  # Actually 1.3.4, but micro versions aren't supported here.



# Add any Sphinx extension module names here, as strings. They can be extensions

# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.

docs/howto/custom-management-commands.txt

+4 −5
Original line number Diff line number Diff line
@@ -139,8 +139,8 @@ parameter of the handle method. See the :py:mod:`argparse` Python documentation 
for more about ``add_argument`` usage.



In addition to being able to add custom command line options, all

:doc:`management commands</ref/django-admin>` can accept some

default options such as :djadminopt:`--verbosity` and :djadminopt:`--traceback`.

:doc:`management commands</ref/django-admin>` can accept some default options

such as :option:`--verbosity` and :option:`--traceback`.



.. _management-commands-and-locales:
@@ -314,9 +314,8 @@ All attributes can be set in your derived class and can be used in 
    see the available styles (use uppercased versions of the "roles" described

    in that section).



    If you pass the :djadminopt:`--no-color` option when running your

    command, all ``self.style()`` calls will return the original string

    uncolored.

    If you pass the :option:`--no-color` option when running your command, all

    ``self.style()`` calls will return the original string uncolored.



Methods

-------

docs/howto/deployment/checklist.txt

+3 −4
Original line number Diff line number Diff line
@@ -32,10 +32,9 @@ module for production. 
Run ``manage.py check --deploy``

================================



Some of the checks described below can be automated using the

:djadminopt:`--deploy` option of the :djadmin:`check` command. Be sure to run it

against your production settings file as described in the option's

documentation.

Some of the checks described below can be automated using the :option:`check

--deploy` option. Be sure to run it against your production settings file as

described in the option's documentation.



Critical settings

=================

docs/internals/contributing/writing-documentation.txt

+2 −1
Original line number Diff line number Diff line
@@ -259,7 +259,8 @@ __ http://sphinx-doc.org/markup/ 


        .. django-admin-option:: --traceback



  To link, use ``:djadminopt:`--traceback```.

  To link, use ``:option:`command_name --traceback``` (or omit ``command_name``

  for the options shared by all commands like ``--verbosity``).



* Links to Trac tickets (typically reserved for patch release notes)::