Fixed #28343 -- Add an OS chooser for docs command line examples.

docs/_ext/djangodocs.py

@@ -7,8 +7,10 @@ import re
 
 from docutils import nodes
 from docutils.parsers.rst import Directive, directives
+from docutils.statemachine import ViewList
 from sphinx import addnodes
 from sphinx.builders.html import StandaloneHTMLBuilder
+from sphinx.directives import CodeBlock
 from sphinx.domains.std import Cmdoption
 from sphinx.util.console import bold
 from sphinx.util.nodes import set_source_info
@@ -68,6 +70,16 @@ def setup(app):
                  texinfo=(visit_snippet_literal, depart_snippet_literal))
     app.set_translator('djangohtml', DjangoHTMLTranslator)
     app.set_translator('json', DjangoHTMLTranslator)
+    app.add_node(
+        ConsoleNode,
+        html=(visit_console_html, None),
+        latex=(visit_console_dummy, depart_console_dummy),
+        man=(visit_console_dummy, depart_console_dummy),
+        text=(visit_console_dummy, depart_console_dummy),
+        texinfo=(visit_console_dummy, depart_console_dummy),
+    )
+    app.add_directive('console', ConsoleDirective)
+    app.connect('html-page-context', html_page_context_hook)
     return {'parallel_read_safe': True}
 
 
@@ -327,3 +339,167 @@ class DjangoStandaloneHTMLBuilder(StandaloneHTMLBuilder):
             fp.write('var django_template_builtins = ')
             json.dump(templatebuiltins, fp)
             fp.write(';\n')
+
+
+class ConsoleNode(nodes.literal_block):
+    """
+    Custom node to override the visit/depart event handlers at registration
+    time. Wrap a literal_block object and defer to it.
+    """
+    def __init__(self, litblk_obj):
+        self.wrapped = litblk_obj
+
+    def __getattr__(self, attr):
+        if attr == 'wrapped':
+            return self.__dict__.wrapped
+        return getattr(self.wrapped, attr)
+
+
+def visit_console_dummy(self, node):
+    """Defer to the corresponding parent's handler."""
+    self.visit_literal_block(node)
+
+
+def depart_console_dummy(self, node):
+    """Defer to the corresponding parent's handler."""
+    self.depart_literal_block(node)
+
+
+def visit_console_html(self, node):
+    """Generate HTML for the console directive."""
+    if self.builder.name in ('djangohtml', 'json') and node['win_console_text']:
+        # Put a mark on the document object signaling the fact the directive
+        # has been used on it.
+        self.document._console_directive_used_flag = True
+        uid = node['uid']
+        self.body.append('''\
+<div class="console-block" id="console-block-%(id)s">
+<input class="c-tab-unix" id="c-tab-%(id)s-unix" type="radio" name="console-%(id)s" checked>
+<label for="c-tab-%(id)s-unix" title="Linux/macOS">&#xf17c/&#xf179</label>
+<input class="c-tab-win" id="c-tab-%(id)s-win" type="radio" name="console-%(id)s">
+<label for="c-tab-%(id)s-win" title="Windows">&#xf17a</label>
+<section class="c-content-unix" id="c-content-%(id)s-unix">\n''' % {'id': uid})
+        try:
+            self.visit_literal_block(node)
+        except nodes.SkipNode:
+            pass
+        self.body.append('</section>\n')
+
+        self.body.append('<section class="c-content-win" id="c-content-%(id)s-win">\n' % {'id': uid})
+        win_text = node['win_console_text']
+        highlight_args = {'force': True}
+        if 'linenos' in node:
+            linenos = node['linenos']
+        else:
+            linenos = win_text.count('\n') >= self.highlightlinenothreshold - 1
+
+        def warner(msg):
+            self.builder.warn(msg, (self.builder.current_docname, node.line))
+
+        highlighted = self.highlighter.highlight_block(
+            win_text, 'doscon', warn=warner, linenos=linenos, **highlight_args
+        )
+        self.body.append(highlighted)
+        self.body.append('</section>\n')
+        self.body.append('</div>\n')
+        raise nodes.SkipNode
+    else:
+        self.visit_literal_block(node)
+
+
+class ConsoleDirective(CodeBlock):
+    """
+    A reStructuredText directive which renders a two-tab code block in which
+    the second tab shows a Windows command line equivalent of the usual
+    Unix-oriented examples.
+    """
+    required_arguments = 0
+    # The 'doscon' Pygments formatter needs a prompt like this. '>' alone
+    # won't do it because then it simply paints the whole command line as a
+    # grey comment with no highlighting at all.
+    WIN_PROMPT = r'...\> '
+
+    def run(self):
+
+        def args_to_win(cmdline):
+            changed = False
+            out = []
+            for token in cmdline.split():
+                if token[:2] == './':
+                    token = token[2:]
+                    changed = True
+                elif token[:2] == '~/':
+                    token = '%HOMEPATH%\\' + token[2:]
+                    changed = True
+                if '://' not in token and 'git' not in cmdline:
+                    out.append(token.replace('/', '\\'))
+                    changed = True
+                else:
+                    out.append(token)
+            if changed:
+                return ' '.join(out)
+            return cmdline
+
+        def cmdline_to_win(line):
+            if line.startswith('# '):
+                return 'REM ' + args_to_win(line[2:])
+            if line.startswith('$ # '):
+                return 'REM ' + args_to_win(line[4:])
+            if line.startswith('$ ./manage.py'):
+                return 'manage.py ' + args_to_win(line[13:])
+            if line.startswith('$ manage.py'):
+                return 'manage.py ' + args_to_win(line[11:])
+            if line.startswith('$ ./runtests.py'):
+                return 'runtests.py ' + args_to_win(line[15:])
+            if line.startswith('$ ./'):
+                return args_to_win(line[4:])
+            if line.startswith('$ python'):
+                return 'py ' + args_to_win(line[8:])
+            if line.startswith('$ '):
+                return args_to_win(line[2:])
+            return None
+
+        def code_block_to_win(content):
+            bchanged = False
+            lines = []
+            for line in content:
+                modline = cmdline_to_win(line)
+                if modline is None:
+                    lines.append(line)
+                else:
+                    lines.append(self.WIN_PROMPT + modline)
+                    bchanged = True
+            if bchanged:
+                return ViewList(lines)
+            return None
+
+        env = self.state.document.settings.env
+        self.arguments = ['console']
+        lit_blk_obj = super().run()[0]
+
+        # Only do work when the djangohtml HTML Sphinx builder is being used,
+        # invoke the default behavior for the rest.
+        if env.app.builder.name not in ('djangohtml', 'json'):
+            return [lit_blk_obj]
+
+        lit_blk_obj['uid'] = '%s' % env.new_serialno('console')
+        # Only add the tabbed UI if there is actually a Windows-specific
+        # version of the CLI example.
+        win_content = code_block_to_win(self.content)
+        if win_content is None:
+            lit_blk_obj['win_console_text'] = None
+        else:
+            self.content = win_content
+            lit_blk_obj['win_console_text'] = super().run()[0].rawsource
+
+        # Replace the literal_node object returned by Sphinx's CodeBlock with
+        # the ConsoleNode wrapper.
+        return [ConsoleNode(lit_blk_obj)]
+
+
+def html_page_context_hook(app, pagename, templatename, context, doctree):
+    # Put a bool on the context used to render the template. It's used to
+    # control inclusion of console-tabs.css and activation of the JavaScript.
+    # This way it's include only from HTML files rendered from reST files where
+    # the ConsoleDirective is used.
+    context['include_console_assets'] = getattr(doctree, '_console_directive_used_flag', False)

docs/_theme/djangodocs/layout.html

@@ -53,8 +53,27 @@
         });
     });
 })(jQuery);
+{%- if include_console_assets -%}
+(function($) {
+    $(document).ready(function() {
+        $(".c-tab-unix").on("click", function() {
+            $("section.c-content-unix").show();
+            $("section.c-content-win").hide();
+            $(".c-tab-unix").prop("checked", true);
+        });
+        $(".c-tab-win").on("click", function() {
+            $("section.c-content-win").show();
+            $("section.c-content-unix").hide();
+            $(".c-tab-win").prop("checked", true);
+        });
+    });
+})(jQuery);
+{%- endif -%}
 </script>
 {% endif %}
+{%- if include_console_assets -%}
+<link rel="stylesheet" href="{{ pathto('_static/console-tabs.css', 1) }}" type="text/css" />
+{%- endif -%}
 {% endblock %}
 
 {% block document %}

docs/_theme/djangodocs/static/console-tabs.css

+@import url("{{ pathto('_static/fontawesome/css/fa-brands.min.css', 1) }}");
+
+.console-block {
+  text-align: right;
+}
+
+.console-block *:before,
+.console-block *:after {
+  box-sizing: border-box;
+}
+
+.console-block > section {
+  display: none;
+  text-align: left;
+}
+
+.console-block > input.c-tab-unix,
+.console-block > input.c-tab-win {
+  display: none;
+}
+
+.console-block > label {
+  display: inline-block;
+  padding: 4px 8px;
+  font-weight: normal;
+  text-align: center;
+  color: #bbb;
+  border: 1px solid transparent;
+  font-family: fontawesome;
+}
+
+.console-block > input:checked + label {
+  color: #555;
+  border: 1px solid #ddd;
+  border-top: 2px solid #ab5603;
+  border-bottom: 1px solid #fff;
+}
+
+.console-block > .c-tab-unix:checked ~ .c-content-unix,
+.console-block > .c-tab-win:checked  ~ .c-content-win {
+  display: block;
+}
+
+.console-block pre {
+  margin-top: 0px;
+}

docs/_theme/djangodocs/static/fontawesome/LICENSE.txt

+Font Awesome Free License
+-------------------------
+
+Font Awesome Free is free, open source, and GPL friendly. You can use it for
+commercial projects, open source projects, or really almost whatever you want.
+Full Font Awesome Free license: https://fontawesome.com/license.
+
+# Icons: CC BY 4.0 License (https://creativecommons.org/licenses/by/4.0/)
+In the Font Awesome Free download, the CC BY 4.0 license applies to all icons
+packaged as SVG and JS file types.
+
+# Fonts: SIL OFL 1.1 License (https://scripts.sil.org/OFL)
+In the Font Awesome Free download, the SIL OLF license applies to all icons
+packaged as web and desktop font files.
+
+# Code: MIT License (https://opensource.org/licenses/MIT)
+In the Font Awesome Free download, the MIT license applies to all non-font and
+non-icon files.
+
+# Attribution
+Attribution is required by MIT, SIL OLF, and CC BY licenses. Downloaded Font
+Awesome Free files already contain embedded comments with sufficient
+attribution, so you shouldn't need to do anything additional when using these
+files normally.
+
+We've kept attribution comments terse, so we ask that you do not actively work
+to remove them from files, especially code. They're a great way for folks to 
+learn about Font Awesome.
+
+# Brand Icons
+All brand icons are trademarks of their respective owners. The use of these
+trademarks does not indicate endorsement of the trademark holder by Font
+Awesome, nor vice versa. **Please do not use brand logos for any purpose except
+to represent the company, product, or service to which they refer.**

docs/_theme/djangodocs/static/fontawesome/README.md

+# Font Awesome 5.0.4
+
+Thanks for downloading Font Awesome! We're so excited you're here.
+
+Our documentation is available online. Just head here:
+
+https://fontawesome.com

docs/_theme/djangodocs/static/fontawesome/css/fa-brands.min.css

+/*!
+ * Font Awesome Free 5.0.4 by @fontawesome - http://fontawesome.com
+ * License - http://fontawesome.com/license (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License)
+ */
+@font-face{font-family:Font Awesome\ 5 Brands;font-style:normal;font-weight:400;src:url(../webfonts/fa-brands-400.eot);src:url(../webfonts/fa-brands-400.eot?#iefix) format("embedded-opentype"),url(../webfonts/fa-brands-400.woff2) format("woff2"),url(../webfonts/fa-brands-400.woff) format("woff"),url(../webfonts/fa-brands-400.ttf) format("truetype"),url(../webfonts/fa-brands-400.svg#fontawesome) format("svg")}.fab{font-family:Font Awesome\ 5 Brands}
\ No newline at end of file

docs/conf.py

@@ -112,7 +112,7 @@ today_fmt = '%B %d, %Y'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['_build']
+exclude_patterns = ['_build', '_theme']
 
 # The reST default role (used for this markup: `text`) to use for all documents.
 # default_role = None

docs/howto/outputting-pdf.txt

@@ -24,7 +24,7 @@ The ReportLab library is `available on PyPI`_. A `user guide`_ (not
 coincidentally, a PDF file) is also available for download.
 You can install ReportLab with ``pip``:
 
-.. code-block:: console
+.. console::
 
     $ pip install reportlab
 

docs/howto/upgrade-version.txt

@@ -62,7 +62,7 @@ In Python, deprecation warnings are silenced by default. You must turn them on
 using the ``-Wall`` Python command line option or the :envvar:`PYTHONWARNINGS`
 environment variable. For example, to show warnings while running tests:
 
-.. code-block:: console
+.. console::
 
     $ python -Wall manage.py test
 
@@ -92,7 +92,7 @@ might want to set up a new environment with all the dependencies first.
 Exactly which steps you will need to take depends on your installation process.
 The most convenient way is to use pip_ with the ``--upgrade`` or ``-U`` flag:
 
-.. code-block:: console
+.. console::
 
    $ pip install -U Django
 
@@ -113,7 +113,7 @@ When the new environment is set up, :doc:`run the full test suite
 on deprecation warnings on so they're shown in the test output (you can also
 use the flag if you test your app manually using ``manage.py runserver``):
 
-.. code-block:: console
+.. console::
 
     $ python -Wall manage.py test
 

docs/internals/contributing/committing-code.txt

@@ -39,7 +39,7 @@ At this point, you can work on the code. Use ``git rebase -i`` and ``git
 commit --amend`` to make sure the commits have the expected level of quality.
 Once you're ready:
 
-.. code-block:: console
+.. console::
 
     $ # Pull in the latest changes from master.
     $ git checkout master

docs/internals/contributing/writing-code/coding-style.txt

@@ -90,7 +90,7 @@ Imports
 
   Quick start:
 
-  .. code-block:: console
+  .. console::
 
       $ pip install isort
       $ isort -rc .

docs/internals/contributing/writing-code/javascript.txt

@@ -53,7 +53,7 @@ To simplify the process of providing optimized JavaScript code, Django
 includes a handy Python script which should be used to create a "minified"
 version. To run it:
 
-.. code-block:: console
+.. console::
 
     $ pip install closure
     $ python django/contrib/admin/bin/compress.py
@@ -134,13 +134,13 @@ To run the tests from the command line, you need to have `Node.js`_ installed.
 After installing `Node.js`, install the JavaScript test dependencies by running
 the following from the root of your Django checkout:
 
-.. code-block:: console
+.. console::
 
     $ npm install
 
 Then run the tests with:
 
-.. code-block:: console
+.. console::
 
     $ npm test
 

docs/internals/contributing/writing-documentation.txt

@@ -269,6 +269,50 @@ docs defines some extra description units:
 
         :ticket:`12345`
 
+Django's documentation uses a custom ``console`` directive for documenting
+command-line examples involving ``django-admin.py``, ``manage.py``, ``python``,
+etc.). In the HTML documentation, it renders a two-tab UI, with one tab showing
+a Unix-style command prompt and a second tab showing a Windows prompt.
+
+For example, you can replace this fragment::
+
+    use this command:
+
+    .. code-block:: console
+
+        $ python manage.py shell
+
+with this one::
+
+    use this command:
+
+    .. console::
+
+        $ python manage.py shell
+
+Notice two things:
+
+* You usually will replace occurrences of the ``.. code-block:: console``
+  directive.
+* You don't need to change the actual content of the code example. You still
+  write it assuming a Unix-y environment (i.e. a ``'$'`` prompt symbol,
+  ``'/'`` as filesystem path components separator, etc.)
+
+The example above will render a code example block with two tabs. The first
+one will show:
+
+.. code-block:: console
+
+    $ python manage.py shell
+
+(No changes from what ``.. code-block:: console`` would have rendered).
+
+The second one will show:
+
+.. code-block:: doscon
+
+    ...\> py manage.py shell
+
 .. _documenting-new-features:
 
 Documenting new features
@@ -337,7 +381,7 @@ AdvanceCOMP's ``advpng``:
 
 .. code-block:: console
 
-   $ cd docs/
+   $ cd docs
    $ optipng -o7 -zm1-9 -i0 -strip all `find . -type f -not -path "./_build/*" -name "*.png"`
    $ advpng -z4 `find . -type f -not -path "./_build/*" -name "*.png"`
 

docs/intro/contributing.txt

@@ -96,12 +96,6 @@ To check whether or not you have Git installed, enter ``git`` into the command
 line. If you get messages saying that this command could not be found, you'll
 have to download and install it, see `Git's download page`__.
 
-.. admonition:: For Windows users
-
-    When installing Git on Windows, it is recommended that you pick the
-    "Git Bash" option so that Git runs in its own shell. This tutorial assumes
-    that's how you have installed it.
-
 If you're not that familiar with Git, you can always find out more about its
 commands (once it's installed) by typing ``git help`` into the command line.
 
@@ -117,7 +111,7 @@ where you'll want your local copy of Django to live.
 
 Download the Django source code repository using the following command:
 
-.. code-block:: console
+.. console::
 
     $ git clone git@github.com:YourGitHubName/django.git
 
@@ -130,30 +124,18 @@ your projects so that they don't interfere with each other.
 It's a good idea to keep all your virtualenvs in one place, for example in
 ``.virtualenvs/`` in your home directory. Create it if it doesn't exist yet:
 
-.. code-block:: console
+.. console::
 
     $ mkdir ~/.virtualenvs
 
 Now create a new virtualenv by running:
 
-.. code-block:: console
+.. console::
 
-    $ python3 -m venv ~/.virtualenvs/djangodev
+    $ python -m venv ~/.virtualenvs/djangodev
 
 The path is where the new environment will be saved on your computer.
 
-.. admonition:: For Windows users
-
-    Using the built-in ``venv`` module will not work if you are also using the
-    Git Bash shell on Windows, since activation scripts are only created for the
-    system shell (``.bat``) and PowerShell (``.ps1``). Use the ``virtualenv``
-    package instead:
-
-    .. code-block:: none
-
-        $ pip install virtualenv
-        $ virtualenv ~/.virtualenvs/djangodev
-
 .. admonition:: For Ubuntu users
 
     On some versions of Ubuntu the above command might fail. Use the
@@ -182,9 +164,9 @@ If the ``source`` command is not available, you can try using a dot instead:
 
     To activate your virtualenv on Windows, run:
 
-    .. code-block:: none
+    .. code-block:: doscon
 
-        $ source ~/virtualenvs/djangodev/Scripts/activate
+        ...\> %HOMEPATH%\.virtualenvs\djangodev\Scripts\activate.bat
 
 You have to activate the virtualenv whenever you open a new terminal window.
 virtualenvwrapper__ is a useful tool for making this more convenient.
@@ -197,7 +179,7 @@ name of the currently activated virtualenv is displayed on the command line to
 help you keep track of which one you are using. Go ahead and install the
 previously cloned copy of Django:
 
-.. code-block:: console
+.. console::
 
     $ pip install -e /path/to/your/local/clone/django/
 
@@ -231,7 +213,7 @@ Navigate into Django's root directory (that's the one that contains ``django``,
 ``docs``, ``tests``, ``AUTHORS``, etc.). You can then check out the older
 revision of Django that we'll be using in the tutorial below:
 
-.. code-block:: console
+.. console::
 
     $ git checkout 4ccfc4439a7add24f8db4ef3960d02ef8ae09887
 
@@ -249,7 +231,7 @@ what its output is supposed to look like.
 Before running the test suite, install its dependencies by first ``cd``-ing
 into the Django ``tests/`` directory and then running:
 
-.. code-block:: console
+.. console::
 
     $ pip install -r requirements/py3.txt
 
@@ -261,7 +243,7 @@ encounter.
 Now we are ready to run the test suite. If you're using GNU/Linux, macOS, or
 some other flavor of Unix, run:
 
-.. code-block:: console
+.. console::
 
     $ ./runtests.py
 
@@ -313,7 +295,7 @@ Creating a branch for your patch
 
 Before making any changes, create a new branch for the ticket:
 
-.. code-block:: console
+.. console::
 
     $ git checkout -b ticket_24788
 
@@ -406,7 +388,7 @@ so our tests are going to fail. Let's run all the tests in the ``forms_tests``
 folder to make sure that's really what happens. From the command line, ``cd``
 into the Django ``tests/`` directory and run:
 
-.. code-block:: console
+.. console::
 
     $ ./runtests.py forms_tests
 
@@ -443,7 +425,7 @@ earlier pass, so we can see whether the code we wrote above is working
 correctly. To run the tests in the ``forms_tests`` folder, ``cd`` into the
 Django ``tests/`` directory and run:
 
-.. code-block:: console
+.. console::
 
     $ ./runtests.py forms_tests
 
@@ -475,7 +457,7 @@ help identify many bugs and regressions that might otherwise go unnoticed.
 To run the entire Django test suite, ``cd`` into the Django ``tests/``
 directory and run:
 
-.. code-block:: console
+.. console::
 
     $ ./runtests.py
 
@@ -517,7 +499,7 @@ Now it's time to go through all the changes made in our patch. To display the
 differences between your current copy of Django (with your changes) and the
 revision that you initially checked out earlier in the tutorial:
 
-.. code-block:: console
+.. console::
 
     $ git diff
 
@@ -612,7 +594,7 @@ Committing the changes in the patch
 
 To commit the changes:
 
-.. code-block:: console
+.. console::
 
     $ git commit -a
 
@@ -629,7 +611,7 @@ Pushing the commit and making a pull request
 After committing the patch, send it to your fork on GitHub (substitute
 "ticket_24788" with the name of your branch if it's different):
 
-.. code-block:: console
+.. console::
 
     $ git push origin ticket_24788
 

docs/intro/overview.txt

@@ -51,7 +51,7 @@ Install it
 Next, run the Django command-line utility to create the database tables
 automatically:
 
-.. code-block:: console
+.. console::
 
     $ python manage.py migrate
 

docs/intro/tutorial01.txt

@@ -16,7 +16,7 @@ We'll assume you have :doc:`Django installed </intro/install>` already. You can
 tell Django is installed and which version by running the following command
 in a shell prompt (indicated by the $ prefix):
 
-.. code-block:: console
+.. console::
 
     $ python -m django --version
 
@@ -52,7 +52,7 @@ application-specific settings.
 From the command line, ``cd`` into a directory where you'd like to store your
 code, then run the following command:
 
-.. code-block:: console
+.. console::
 
    $ django-admin startproject mysite
 
@@ -123,7 +123,7 @@ The development server
 Let's verify your Django project works. Change into the outer :file:`mysite` directory, if
 you haven't already, and run the following commands:
 
-.. code-block:: console
+.. console::
 
    $ python manage.py runserver
 
@@ -169,7 +169,7 @@ It worked!
     it as a command-line argument. For instance, this command starts the server
     on port 8080:
 
-    .. code-block:: console
+    .. console::
 
         $ python manage.py runserver 8080
 
@@ -178,7 +178,7 @@ It worked!
     running Vagrant or want to show off your work on other computers on the
     network), use:
 
-    .. code-block:: console
+    .. console::
 
         $ python manage.py runserver 0:8000
 
@@ -219,7 +219,7 @@ submodule of ``mysite``.
 To create your app, make sure you're in the same directory as :file:`manage.py`
 and type this command:
 
-.. code-block:: console
+.. console::
 
     $ python manage.py startapp polls
 
@@ -316,7 +316,7 @@ app will still work.
 You have now wired an ``index`` view into the URLconf. Lets verify it's
 working, run the following command:
 
-.. code-block:: console
+.. console::
 
    $ python manage.py runserver
 

docs/intro/tutorial02.txt

@@ -85,7 +85,7 @@ Some of these applications make use of at least one database table, though,
 so we need to create the tables in the database before we can use them. To do
 that, run the following command:
 
-.. code-block:: console
+.. console::
 
     $ python manage.py migrate
 
@@ -226,7 +226,7 @@ this:
 
 Now Django knows to include the ``polls`` app. Let's run another command:
 
-.. code-block:: console
+.. console::
 
     $ python manage.py makemigrations polls
 
@@ -256,7 +256,7 @@ schema automatically - that's called :djadmin:`migrate`, and we'll come to it in
 moment - but first, let's see what SQL that migration would run. The
 :djadmin:`sqlmigrate` command takes migration names and returns their SQL:
 
-.. code-block:: console
+.. console::
 
     $ python manage.py sqlmigrate polls 0001
 
@@ -332,7 +332,7 @@ your project without making migrations or touching the database.
 
 Now, run :djadmin:`migrate` again to create those model tables in your database:
 
-.. code-block:: console
+.. console::
 
     $ python manage.py migrate
     Operations to perform:
@@ -373,7 +373,7 @@ Playing with the API
 Now, let's hop into the interactive Python shell and play around with the free
 API Django gives you. To invoke the Python shell, use this command:
 
-.. code-block:: console
+.. console::
 
     $ python manage.py shell
 
@@ -575,7 +575,7 @@ Creating an admin user
 First we'll need to create a user who can login to the admin site. Run the
 following command:
 
-.. code-block:: console
+.. console::
 
     $ python manage.py createsuperuser
 
@@ -608,7 +608,7 @@ server and explore it.
 
 If the server is not running start it like so:
 
-.. code-block:: console
+.. console::
 
     $ python manage.py runserver
 

docs/intro/tutorial07.txt

@@ -342,7 +342,7 @@ template directory in the source code of Django itself
     If you have difficulty finding where the Django source files are located
     on your system, run the following command:
 
-    .. code-block:: console
+    .. console::
 
         $ python -c "import django; print(django.__path__)"
 

docs/intro/whatsnext.txt

@@ -150,7 +150,7 @@ Unix ``grep`` utility to search for a phrase in all of the documentation. For
 example, this will show you each mention of the phrase "max_length" in any
 Django document:
 
-.. code-block:: console
+.. console::
 
     $ grep -r max_length /path/to/django/docs/
 
@@ -163,7 +163,7 @@ You can get a local copy of the HTML documentation following a few easy steps:
   plain text to HTML. You'll need to install Sphinx by either downloading
   and installing the package from the Sphinx website, or with ``pip``:
 
-  .. code-block:: console
+  .. console::
 
         $ pip install Sphinx
 

docs/ref/contrib/gis/tutorial.txt

@@ -58,14 +58,14 @@ Create a New Project
 Use the standard ``django-admin`` script to create a project called
 ``geodjango``:
 
-.. code-block:: console
+.. console::
 
     $ django-admin startproject geodjango
 
 This will initialize a new project. Now, create a ``world`` Django application
 within the ``geodjango`` project:
 
-.. code-block:: console
+.. console::
 
     $ cd geodjango
     $ python manage.py startapp world
@@ -111,7 +111,7 @@ The world borders data is available in this `zip file`__.  Create a ``data``
 directory in the ``world`` application, download the world borders data, and
 unzip. On GNU/Linux platforms, use the following commands:
 
-.. code-block:: console
+.. console::
 
     $ mkdir world/data
     $ cd world/data
@@ -140,7 +140,7 @@ Use ``ogrinfo`` to examine spatial data
 The GDAL ``ogrinfo`` utility allows examining the metadata of shapefiles or
 other vector data sources:
 
-.. code-block:: console
+.. console::
 
     $ ogrinfo world/data/TM_WORLD_BORDERS-0.3.shp
     INFO: Open of `world/data/TM_WORLD_BORDERS-0.3.shp'
@@ -151,7 +151,7 @@ other vector data sources:
 layer contains polygon data.  To find out more, we'll specify the layer name
 and use the ``-so`` option to get only the important summary information:
 
-.. code-block:: console
+.. console::
 
     $ ogrinfo -so world/data/TM_WORLD_BORDERS-0.3.shp TM_WORLD_BORDERS-0.3
     INFO: Open of `world/data/TM_WORLD_BORDERS-0.3.shp'
@@ -235,7 +235,7 @@ Run ``migrate``
 After defining your model, you need to sync it with the database. First,
 create a database migration:
 
-.. code-block:: console
+.. console::
 
     $ python manage.py makemigrations
     Migrations for 'world':
@@ -245,13 +245,13 @@ create a database migration:
 Let's look at the SQL that will generate the table for the ``WorldBorder``
 model:
 
-.. code-block:: console
+.. console::
 
     $ python manage.py sqlmigrate world 0001
 
 This command should produce the following output:
 
-.. code-block:: sql
+.. console::
 
     BEGIN;
     --
@@ -279,7 +279,7 @@ This command should produce the following output:
 If this looks correct, run :djadmin:`migrate` to create this table in the
 database:
 
-.. code-block:: console
+.. console::
 
     $ python manage.py migrate
     Operations to perform:
@@ -316,7 +316,7 @@ library that can work with all the vector data sources that OGR supports.
 
 First, invoke the Django shell:
 
-.. code-block:: console
+.. console::
 
     $ python manage.py shell
 
@@ -483,7 +483,7 @@ A few notes about what's going on:
 
 Afterwards, invoke the Django shell from the ``geodjango`` project directory:
 
-.. code-block:: console
+.. console::
 
     $ python manage.py shell
 
@@ -505,7 +505,7 @@ and generates a model definition and ``LayerMapping`` dictionary automatically.
 
 The general usage of the command goes as follows:
 
-.. code-block:: console
+.. console::
 
     $ python manage.py ogrinspect [options] <data_source> <model_name> [options]
 
@@ -516,7 +516,7 @@ be used to further define how the model is generated.
 For example, the following command nearly reproduces the ``WorldBorder`` model
 and mapping dictionary created above, automatically:
 
-.. code-block:: console
+.. console::
 
     $ python manage.py ogrinspect world/data/TM_WORLD_BORDERS-0.3.shp WorldBorder \
         --srid=4326 --mapping --multi
@@ -576,7 +576,7 @@ GeoDjango adds spatial lookups to the Django ORM.  For example, you
 can find the country in the ``WorldBorder`` table that contains
 a particular point.  First, fire up the management shell:
 
-.. code-block:: console
+.. console::
 
     $ python manage.py shell
 
@@ -730,13 +730,13 @@ Next, edit your ``urls.py`` in the ``geodjango`` application folder as follows::
 
 Create an admin user:
 
-.. code-block:: console
+.. console::
 
     $ python manage.py createsuperuser
 
 Next, start up the Django development server:
 
-.. code-block:: console
+.. console::
 
     $ python manage.py runserver
 

docs/ref/django-admin.txt

@@ -37,7 +37,7 @@ just as well.
 Usage
 =====
 
-.. code-block:: console
+.. console::
 
     $ django-admin <command> [options]
     $ manage.py <command> [options]

docs/topics/install.txt

@@ -140,7 +140,7 @@ uninstalling is as simple as deleting the ``django`` directory from your Python
 ``site-packages``. To find the directory you need to remove, you can run the
 following at your shell prompt (not the interactive Python prompt):
 
-.. code-block:: console
+.. console::
 
     $ python -c "import django; print(django.__path__)"
 
@@ -218,7 +218,7 @@ latest bug fixes and improvements, follow these instructions:
 
 2. Check out Django's main development branch like so:
 
-   .. code-block:: console
+   .. console::
 
         $ git clone https://github.com/django/django.git
 
@@ -231,7 +231,7 @@ latest bug fixes and improvements, follow these instructions:
 
 4. After setting up and activating the virtualenv, run the following command:
 
-   .. code-block:: console
+   .. console::
 
         $ pip install -e django/
 

docs/topics/templates.txt

@@ -383,7 +383,7 @@ applications. This generic name was kept for backwards-compatibility.
 
 Requires Jinja2_ to be installed:
 
-.. code-block:: console
+.. console::
 
     $ pip install Jinja2
 

docs/topics/testing/tools.txt

@@ -857,7 +857,7 @@ To demonstrate how to use ``LiveServerTestCase``, let's write a simple Selenium
 test. First of all, you need to install the `selenium package`_ into your
 Python path:
 
-.. code-block:: console
+.. console::
 
     $ pip install selenium
 
@@ -900,7 +900,7 @@ The code for this test may look as follows::
 
 Finally, you may run the test as follows:
 
-.. code-block:: console
+.. console::
 
     $ ./manage.py test myapp.tests.MySeleniumTests.test_login
 
@@ -1640,19 +1640,19 @@ class. Given::
 
 Then you can choose which tests to run. For example, to run only fast tests:
 
-.. code-block:: console
+.. console::
 
     $ ./manage.py test --tag=fast
 
 Or to run fast tests and the core one (even though it's slow):
 
-.. code-block:: console
+.. console::
 
     $ ./manage.py test --tag=fast --tag=core
 
 You can also exclude tests by tag. To run core tests if they are not slow:
 
-.. code-block:: console
+.. console::
 
     $ ./manage.py test --tag=core --exclude-tag=slow