diff --git a/docs/_ext/djangodocs.py b/docs/_ext/djangodocs.py index 21abe99063..1512d9c261 100644 --- a/docs/_ext/djangodocs.py +++ b/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('''\ +
+ + + + +
\n''' % {'id': uid}) + try: + self.visit_literal_block(node) + except nodes.SkipNode: + pass + self.body.append('
\n') + + self.body.append('
\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('
\n') + self.body.append('
\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) diff --git a/docs/_theme/djangodocs/layout.html b/docs/_theme/djangodocs/layout.html index f90030852c..acf83a47cd 100644 --- a/docs/_theme/djangodocs/layout.html +++ b/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 -%} {% endif %} +{%- if include_console_assets -%} + +{%- endif -%} {% endblock %} {% block document %} diff --git a/docs/_theme/djangodocs/static/console-tabs.css b/docs/_theme/djangodocs/static/console-tabs.css new file mode 100644 index 0000000000..c13ec7b1ac --- /dev/null +++ b/docs/_theme/djangodocs/static/console-tabs.css @@ -0,0 +1,46 @@ +@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; +} diff --git a/docs/_theme/djangodocs/static/fontawesome/LICENSE.txt b/docs/_theme/djangodocs/static/fontawesome/LICENSE.txt new file mode 100644 index 0000000000..28c1c4bc73 --- /dev/null +++ b/docs/_theme/djangodocs/static/fontawesome/LICENSE.txt @@ -0,0 +1,34 @@ +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.** diff --git a/docs/_theme/djangodocs/static/fontawesome/README.md b/docs/_theme/djangodocs/static/fontawesome/README.md new file mode 100644 index 0000000000..72a373e348 --- /dev/null +++ b/docs/_theme/djangodocs/static/fontawesome/README.md @@ -0,0 +1,7 @@ +# 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 diff --git a/docs/_theme/djangodocs/static/fontawesome/css/fa-brands.min.css b/docs/_theme/djangodocs/static/fontawesome/css/fa-brands.min.css new file mode 100644 index 0000000000..244a01ef98 --- /dev/null +++ b/docs/_theme/djangodocs/static/fontawesome/css/fa-brands.min.css @@ -0,0 +1,5 @@ +/*! + * 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 diff --git a/docs/_theme/djangodocs/static/fontawesome/webfonts/fa-brands-400.eot b/docs/_theme/djangodocs/static/fontawesome/webfonts/fa-brands-400.eot new file mode 100644 index 0000000000..45f12a121f Binary files /dev/null and b/docs/_theme/djangodocs/static/fontawesome/webfonts/fa-brands-400.eot differ diff --git a/docs/_theme/djangodocs/static/fontawesome/webfonts/fa-brands-400.svg b/docs/_theme/djangodocs/static/fontawesome/webfonts/fa-brands-400.svg new file mode 100644 index 0000000000..2f26609a1a --- /dev/null +++ b/docs/_theme/djangodocs/static/fontawesome/webfonts/fa-brands-400.svg @@ -0,0 +1,996 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/_theme/djangodocs/static/fontawesome/webfonts/fa-brands-400.ttf b/docs/_theme/djangodocs/static/fontawesome/webfonts/fa-brands-400.ttf new file mode 100644 index 0000000000..ed62125e40 Binary files /dev/null and b/docs/_theme/djangodocs/static/fontawesome/webfonts/fa-brands-400.ttf differ diff --git a/docs/_theme/djangodocs/static/fontawesome/webfonts/fa-brands-400.woff b/docs/_theme/djangodocs/static/fontawesome/webfonts/fa-brands-400.woff new file mode 100644 index 0000000000..dc90ab137a Binary files /dev/null and b/docs/_theme/djangodocs/static/fontawesome/webfonts/fa-brands-400.woff differ diff --git a/docs/_theme/djangodocs/static/fontawesome/webfonts/fa-brands-400.woff2 b/docs/_theme/djangodocs/static/fontawesome/webfonts/fa-brands-400.woff2 new file mode 100644 index 0000000000..d14f86eb86 Binary files /dev/null and b/docs/_theme/djangodocs/static/fontawesome/webfonts/fa-brands-400.woff2 differ diff --git a/docs/conf.py b/docs/conf.py index 639438a3ac..8094cdd2e1 100644 --- a/docs/conf.py +++ b/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 diff --git a/docs/howto/outputting-pdf.txt b/docs/howto/outputting-pdf.txt index 7f1b9d1b1a..39114d45bf 100644 --- a/docs/howto/outputting-pdf.txt +++ b/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 diff --git a/docs/howto/upgrade-version.txt b/docs/howto/upgrade-version.txt index c495bd79e5..83dc50e001 100644 --- a/docs/howto/upgrade-version.txt +++ b/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 diff --git a/docs/internals/contributing/committing-code.txt b/docs/internals/contributing/committing-code.txt index a56bf48281..84eff3fc11 100644 --- a/docs/internals/contributing/committing-code.txt +++ b/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 diff --git a/docs/internals/contributing/writing-code/coding-style.txt b/docs/internals/contributing/writing-code/coding-style.txt index 1924e39e1d..bd016b1d64 100644 --- a/docs/internals/contributing/writing-code/coding-style.txt +++ b/docs/internals/contributing/writing-code/coding-style.txt @@ -90,7 +90,7 @@ Imports Quick start: - .. code-block:: console + .. console:: $ pip install isort $ isort -rc . diff --git a/docs/internals/contributing/writing-code/javascript.txt b/docs/internals/contributing/writing-code/javascript.txt index 5d96e19e25..c5ed842637 100644 --- a/docs/internals/contributing/writing-code/javascript.txt +++ b/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 diff --git a/docs/internals/contributing/writing-documentation.txt b/docs/internals/contributing/writing-documentation.txt index d58c318408..696691aff4 100644 --- a/docs/internals/contributing/writing-documentation.txt +++ b/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"` diff --git a/docs/intro/contributing.txt b/docs/intro/contributing.txt index ac81e13610..07d9aae379 100644 --- a/docs/intro/contributing.txt +++ b/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 diff --git a/docs/intro/overview.txt b/docs/intro/overview.txt index 203e501054..f6e34b0695 100644 --- a/docs/intro/overview.txt +++ b/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 diff --git a/docs/intro/tutorial01.txt b/docs/intro/tutorial01.txt index c9f1b4b057..1904e5474e 100644 --- a/docs/intro/tutorial01.txt +++ b/docs/intro/tutorial01.txt @@ -16,7 +16,7 @@ We'll assume you have :doc:`Django installed ` 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 diff --git a/docs/intro/tutorial02.txt b/docs/intro/tutorial02.txt index e9b2aaa2a3..12e1a73630 100644 --- a/docs/intro/tutorial02.txt +++ b/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 diff --git a/docs/intro/tutorial07.txt b/docs/intro/tutorial07.txt index 04f2fa7060..5924f55c6a 100644 --- a/docs/intro/tutorial07.txt +++ b/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__)" diff --git a/docs/intro/whatsnext.txt b/docs/intro/whatsnext.txt index 019dfed3a9..e7d3dad818 100644 --- a/docs/intro/whatsnext.txt +++ b/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 diff --git a/docs/ref/contrib/gis/tutorial.txt b/docs/ref/contrib/gis/tutorial.txt index 33c9ebabfd..8ffa41d4a2 100644 --- a/docs/ref/contrib/gis/tutorial.txt +++ b/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] [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 diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt index 61037894cb..b97c6f3f2a 100644 --- a/docs/ref/django-admin.txt +++ b/docs/ref/django-admin.txt @@ -37,7 +37,7 @@ just as well. Usage ===== -.. code-block:: console +.. console:: $ django-admin [options] $ manage.py [options] diff --git a/docs/topics/install.txt b/docs/topics/install.txt index b2898bf241..19b3a03771 100644 --- a/docs/topics/install.txt +++ b/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/ diff --git a/docs/topics/templates.txt b/docs/topics/templates.txt index 1c4a1c4f03..297008668f 100644 --- a/docs/topics/templates.txt +++ b/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 diff --git a/docs/topics/testing/tools.txt b/docs/topics/testing/tools.txt index 65d1fb463b..c7ae792fb5 100644 --- a/docs/topics/testing/tools.txt +++ b/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