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

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.
parent fd1c5bb0

django/core/management/commands/showmigrations.py

+2 −2
Original line number Diff line number Diff line
@@ -10,7 +10,7 @@ class Command(BaseCommand): 
    help = "Shows all available migrations for the current project"



    def add_arguments(self, parser):

        parser.add_argument('app_labels', nargs='*',

        parser.add_argument('app_label', nargs='*',

            help='App labels of applications to limit the output to.')

        parser.add_argument('--database', action='store', dest='database', default=DEFAULT_DB_ALIAS,

            help='Nominates a database to synchronize. Defaults to the "default" database.')
@@ -33,7 +33,7 @@ class Command(BaseCommand): 
        if options['format'] == "plan":

            return self.show_plan(connection)

        else:

            return self.show_list(connection, options['app_labels'])

            return self.show_list(connection, options['app_label'])



    def show_list(self, connection, app_names=None):

        """

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 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)
@@ -295,39 +291,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.8'

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
@@ -123,8 +123,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:
@@ -267,9 +267,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

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