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
Loading
Loading
Loading
Loading
+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):
+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.
+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
-------
+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
=================
+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)::

Loading