From 1853e2dbf2e290ec04e3389d523bbe4bad94a42e Mon Sep 17 00:00:00 2001 From: Curtis Maloney Date: Tue, 11 Sep 2018 03:00:34 +1000 Subject: [PATCH] [2.1.x] Refs #20910 -- Replaced snippet directive with code-block. Backport of c49ea6f5911296dcb40190c905e38b43cdc7c7a3 from master --- docs/_ext/djangodocs.py | 141 +----------------- docs/_theme/djangodocs-epub/static/epub.css | 5 +- docs/_theme/djangodocs/static/djangodocs.css | 5 +- docs/howto/initial-data.txt | 2 +- docs/howto/writing-migrations.txt | 20 +-- .../writing-code/coding-style.txt | 4 +- .../contributing/writing-code/unit-tests.txt | 4 +- docs/internals/howto-release-django.txt | 4 +- docs/intro/overview.txt | 28 ++-- docs/intro/reusable-apps.txt | 12 +- docs/intro/tutorial01.txt | 12 +- docs/intro/tutorial02.txt | 20 +-- docs/intro/tutorial03.txt | 52 +++---- docs/intro/tutorial04.txt | 28 ++-- docs/intro/tutorial05.txt | 40 ++--- docs/intro/tutorial06.txt | 12 +- docs/intro/tutorial07.txt | 36 ++--- docs/ref/contrib/admin/index.txt | 20 +-- docs/ref/contrib/admin/javascript.txt | 8 +- docs/ref/models/expressions.txt | 4 +- docs/ref/models/fields.txt | 8 +- docs/ref/templates/language.txt | 16 +- docs/releases/1.9.txt | 16 +- docs/topics/auth/passwords.txt | 12 +- .../class-based-views/generic-editing.txt | 28 ++-- docs/topics/class-based-views/mixins.txt | 8 +- docs/topics/db/models.txt | 4 +- docs/topics/forms/index.txt | 16 +- docs/topics/http/file-uploads.txt | 16 +- docs/topics/http/urls.txt | 16 +- docs/topics/logging.txt | 4 +- docs/topics/testing/advanced.txt | 8 +- 32 files changed, 234 insertions(+), 375 deletions(-) diff --git a/docs/_ext/djangodocs.py b/docs/_ext/djangodocs.py index 95f5218d70..30d3741b89 100644 --- a/docs/_ext/djangodocs.py +++ b/docs/_ext/djangodocs.py @@ -6,14 +6,13 @@ import os import re from docutils import nodes -from docutils.parsers.rst import Directive, directives +from docutils.parsers.rst import Directive 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 from sphinx.writers.html import HTMLTranslator # RE for option descriptions without a '--' prefix @@ -53,17 +52,6 @@ def setup(app): app.add_directive('versionadded', VersionDirective) app.add_directive('versionchanged', VersionDirective) app.add_builder(DjangoStandaloneHTMLBuilder) - - # register the snippet directive - app.add_directive('snippet', SnippetWithFilename) - # register a node for snippet directive so that the xml parser - # knows how to handle the enter/exit parsing event - app.add_node(snippet_with_filename, - html=(visit_snippet, depart_snippet_literal), - latex=(visit_snippet_latex, depart_snippet_latex), - man=(visit_snippet_literal, depart_snippet_literal), - text=(visit_snippet_literal, depart_snippet_literal), - texinfo=(visit_snippet_literal, depart_snippet_literal)) app.set_translator('djangohtml', DjangoHTMLTranslator) app.set_translator('json', DjangoHTMLTranslator) app.add_node( @@ -79,133 +67,6 @@ def setup(app): return {'parallel_read_safe': True} -class snippet_with_filename(nodes.literal_block): - """ - Subclass the literal_block to override the visit/depart event handlers - """ - pass - - -def visit_snippet_literal(self, node): - """ - default literal block handler - """ - self.visit_literal_block(node) - - -def depart_snippet_literal(self, node): - """ - default literal block handler - """ - self.depart_literal_block(node) - - -def visit_snippet(self, node): - """ - HTML document generator visit handler - """ - lang = self.highlightlang - linenos = node.rawsource.count('\n') >= self.highlightlinenothreshold - 1 - fname = node['filename'] - highlight_args = node.get('highlight_args', {}) - if 'language' in node: - # code-block directives - lang = node['language'] - highlight_args['force'] = True - if 'linenos' in node: - linenos = node['linenos'] - - def warner(msg): - self.builder.warn(msg, (self.builder.current_docname, node.line)) - - highlighted = self.highlighter.highlight_block(node.rawsource, lang, - warn=warner, - linenos=linenos, - **highlight_args) - starttag = self.starttag(node, 'div', suffix='', - CLASS='highlight-%s snippet' % lang) - self.body.append(starttag) - self.body.append('
%s
\n''' % (fname,)) - self.body.append(highlighted) - self.body.append('\n') - raise nodes.SkipNode - - -def visit_snippet_latex(self, node): - """ - Latex document generator visit handler - """ - code = node.rawsource.rstrip('\n') - - lang = self.hlsettingstack[-1][0] - linenos = code.count('\n') >= self.hlsettingstack[-1][1] - 1 - fname = node['filename'] - highlight_args = node.get('highlight_args', {}) - if 'language' in node: - # code-block directives - lang = node['language'] - highlight_args['force'] = True - if 'linenos' in node: - linenos = node['linenos'] - - def warner(msg): - self.builder.warn(msg, (self.curfilestack[-1], node.line)) - - hlcode = self.highlighter.highlight_block(code, lang, warn=warner, - linenos=linenos, - **highlight_args) - - self.body.append( - '\n{\\colorbox[rgb]{0.9,0.9,0.9}' - '{\\makebox[\\textwidth][l]' - '{\\small\\texttt{%s}}}}\n' % ( - # Some filenames have '_', which is special in latex. - fname.replace('_', r'\_'), - ) - ) - - if self.table: - hlcode = hlcode.replace('\\begin{Verbatim}', - '\\begin{OriginalVerbatim}') - self.table.has_problematic = True - self.table.has_verbatim = True - - hlcode = hlcode.rstrip()[:-14] # strip \end{Verbatim} - hlcode = hlcode.rstrip() + '\n' - self.body.append('\n' + hlcode + '\\end{%sVerbatim}\n' % - (self.table and 'Original' or '')) - - # Prevent rawsource from appearing in output a second time. - raise nodes.SkipNode - - -def depart_snippet_latex(self, node): - """ - Latex document generator depart handler. - """ - pass - - -class SnippetWithFilename(Directive): - """ - The 'snippet' directive that allows to add the filename (optional) - of a code snippet in the document. This is modeled after CodeBlock. - """ - has_content = True - optional_arguments = 1 - option_spec = {'filename': directives.unchanged_required} - - def run(self): - code = '\n'.join(self.content) - - literal = snippet_with_filename(code, code) - if self.arguments: - literal['language'] = self.arguments[0] - literal['filename'] = self.options['filename'] - set_source_info(self, literal) - return [literal] - - class VersionDirective(Directive): has_content = True required_arguments = 1 diff --git a/docs/_theme/djangodocs-epub/static/epub.css b/docs/_theme/djangodocs-epub/static/epub.css index b74af5e9bf..7db68b53fb 100644 --- a/docs/_theme/djangodocs-epub/static/epub.css +++ b/docs/_theme/djangodocs-epub/static/epub.css @@ -29,15 +29,14 @@ pre { } /* Header for some code blocks. */ -.snippet-filename { +.code-block-caption { background-color: #393939; color: white; margin: 0; padding: 0.5em; font: bold 90% monospace; } -.snippet-filename + .highlight > pre, -.snippet-filename + pre { +.literal-block-wrapper pre { margin-top: 0; } diff --git a/docs/_theme/djangodocs/static/djangodocs.css b/docs/_theme/djangodocs/static/djangodocs.css index 143bcdb6c9..1a397f44c0 100644 --- a/docs/_theme/djangodocs/static/djangodocs.css +++ b/docs/_theme/djangodocs/static/djangodocs.css @@ -101,9 +101,8 @@ pre { font-size:small; background:#E0FFB8; border:1px solid #94da3a; border-widt dt .literal, table .literal { background:none; } #bd a.reference { text-decoration: none; } #bd a.reference tt.literal { border-bottom: 1px #234f32 dotted; } -div.snippet-filename { color: white; background-color: #234F32; margin: 0; padding: 2px 5px; width: 100%; font-family: monospace; font-size: small; line-height: 1.3em; } -div.snippet-filename + div.highlight > pre { margin-top: 0; } -div.snippet-filename + pre { margin-top: 0; } +div.code-block-caption { color: white; background-color: #234F32; margin: 0; padding: 2px 5px; width: 100%; font-family: monospace; font-size: small; line-height: 1.3em; } +div.literal-block-wrapper pre { margin-top: 0; } /* Restore colors of pygments hyperlinked code */ #bd .highlight .k a:link, #bd .highlight .k a:visited { color: #000000; text-decoration: none; border-bottom: 1px dotted #000000; } diff --git a/docs/howto/initial-data.txt b/docs/howto/initial-data.txt index 64012f66b9..fcfecc82a1 100644 --- a/docs/howto/initial-data.txt +++ b/docs/howto/initial-data.txt @@ -58,7 +58,7 @@ look like in JSON: And here's that same fixture as YAML: -.. code-block:: none +.. code-block:: yaml - model: myapp.person pk: 1 diff --git a/docs/howto/writing-migrations.txt b/docs/howto/writing-migrations.txt index 4596f64eb6..f98a56c534 100644 --- a/docs/howto/writing-migrations.txt +++ b/docs/howto/writing-migrations.txt @@ -39,8 +39,8 @@ attribute:: You can also provide hints that will be passed to the :meth:`allow_migrate()` method of database routers as ``**hints``: -.. snippet:: - :filename: myapp/dbrouters.py +.. code-block:: python + :caption: myapp/dbrouters.py class MyRouter: @@ -97,8 +97,8 @@ the respective field according to your needs. of the three new files) to the last migration, change ``AddField`` to ``AlterField``, and add imports of ``uuid`` and ``models``. For example: - .. snippet:: - :filename: 0006_remove_uuid_null.py + .. code-block:: python + :caption: 0006_remove_uuid_null.py # Generated by Django A.B on YYYY-MM-DD HH:MM from django.db import migrations, models @@ -121,8 +121,8 @@ the respective field according to your needs. * Edit the first migration file. The generated migration class should look similar to this: - .. snippet:: - :filename: 0004_add_uuid_field.py + .. code-block:: python + :caption: 0004_add_uuid_field.py class Migration(migrations.Migration): @@ -148,8 +148,8 @@ the respective field according to your needs. unique value (UUID in the example) for each existing row. Also add an import of ``uuid``. For example: - .. snippet:: - :filename: 0005_populate_uuid_values.py + .. code-block:: python + :caption: 0005_populate_uuid_values.py # Generated by Django A.B on YYYY-MM-DD HH:MM from django.db import migrations @@ -279,8 +279,8 @@ project anywhere without first installing and then uninstalling the old app. Here's a sample migration: -.. snippet:: - :filename: myapp/migrations/0124_move_old_app_to_new_app.py +.. code-block:: python + :caption: myapp/migrations/0124_move_old_app_to_new_app.py from django.apps import apps as global_apps from django.db import migrations diff --git a/docs/internals/contributing/writing-code/coding-style.txt b/docs/internals/contributing/writing-code/coding-style.txt index 36203e3ab7..4b37f1f3c6 100644 --- a/docs/internals/contributing/writing-code/coding-style.txt +++ b/docs/internals/contributing/writing-code/coding-style.txt @@ -123,8 +123,8 @@ Imports For example (comments are for explanatory purposes only): - .. snippet:: - :filename: django/contrib/admin/example.py + .. code-block:: python + :caption: django/contrib/admin/example.py # future from __future__ import unicode_literals diff --git a/docs/internals/contributing/writing-code/unit-tests.txt b/docs/internals/contributing/writing-code/unit-tests.txt index 7ce2da08ef..973ed27644 100644 --- a/docs/internals/contributing/writing-code/unit-tests.txt +++ b/docs/internals/contributing/writing-code/unit-tests.txt @@ -446,8 +446,8 @@ Since this pattern involves a lot of boilerplate, Django provides the :func:`~django.test.utils.isolate_apps` instances are correctly installed, you should pass the set of targeted ``app_label`` as arguments: - .. snippet:: - :filename: tests/app_label/tests.py + .. code-block:: python + :caption: tests/app_label/tests.py from django.db import models from django.test import SimpleTestCase diff --git a/docs/internals/howto-release-django.txt b/docs/internals/howto-release-django.txt index 41529d8ea4..c6c05758da 100644 --- a/docs/internals/howto-release-django.txt +++ b/docs/internals/howto-release-django.txt @@ -62,8 +62,8 @@ You'll need a few things before getting started: * Access to Django's record on PyPI. Create a file with your credentials: - .. snippet:: - :filename: ~/.pypirc + .. code-block:: ini + :caption: ~/.pypirc [pypi] username:YourUsername diff --git a/docs/intro/overview.txt b/docs/intro/overview.txt index e091ab0229..82b7a71a60 100644 --- a/docs/intro/overview.txt +++ b/docs/intro/overview.txt @@ -25,8 +25,8 @@ The :doc:`data-model syntax ` offers many rich ways of representing your models -- so far, it's been solving many years' worth of database-schema problems. Here's a quick example: -.. snippet:: - :filename: mysite/news/models.py +.. code-block:: python + :caption: mysite/news/models.py from django.db import models @@ -145,8 +145,8 @@ production ready :doc:`administrative interface ` -- a website that lets authenticated users add, change and delete objects. It's as easy as registering your model in the admin site: -.. snippet:: - :filename: mysite/news/models.py +.. code-block:: python + :caption: mysite/news/models.py from django.db import models @@ -156,8 +156,8 @@ as easy as registering your model in the admin site: content = models.TextField() reporter = models.ForeignKey(Reporter, on_delete=models.CASCADE) -.. snippet:: - :filename: mysite/news/admin.py +.. code-block:: python + :caption: mysite/news/admin.py from django.contrib import admin @@ -188,8 +188,8 @@ to decouple URLs from Python code. Here's what a URLconf might look like for the ``Reporter``/``Article`` example above: -.. snippet:: - :filename: mysite/news/urls.py +.. code-block:: python + :caption: mysite/news/urls.py from django.urls import path @@ -228,8 +228,8 @@ Generally, a view retrieves data according to the parameters, loads a template and renders the template with the retrieved data. Here's an example view for ``year_archive`` from above: -.. snippet:: - :filename: mysite/news/views.py +.. code-block:: python + :caption: mysite/news/views.py from django.shortcuts import render @@ -257,8 +257,8 @@ in the first directory, it checks the second, and so on. Let's say the ``news/year_archive.html`` template was found. Here's what that might look like: -.. snippet:: html+django - :filename: mysite/news/templates/news/year_archive.html +.. code-block:: html+django + :caption: mysite/news/templates/news/year_archive.html {% extends "base.html" %} @@ -298,8 +298,8 @@ in templates: each template has to define only what's unique to that template. Here's what the "base.html" template, including the use of :doc:`static files `, might look like: -.. snippet:: html+django - :filename: mysite/templates/base.html +.. code-block:: html+django + :caption: mysite/templates/base.html {% load static %} diff --git a/docs/intro/reusable-apps.txt b/docs/intro/reusable-apps.txt index 8b71b523a4..e76bab8173 100644 --- a/docs/intro/reusable-apps.txt +++ b/docs/intro/reusable-apps.txt @@ -141,8 +141,8 @@ this. For a small app like polls, this process isn't too difficult. 3. Create a file ``django-polls/README.rst`` with the following contents: - .. snippet:: - :filename: django-polls/README.rst + .. code-block:: rst + :caption: django-polls/README.rst ===== Polls @@ -188,8 +188,8 @@ this. For a small app like polls, this process isn't too difficult. explanation. Create a file ``django-polls/setup.py`` with the following contents: - .. snippet:: - :filename: django-polls/setup.py + .. code-block:: python + :caption: django-polls/setup.py import os from setuptools import find_packages, setup @@ -233,8 +233,8 @@ this. For a small app like polls, this process isn't too difficult. file, create a file ``django-polls/MANIFEST.in`` with the following contents: - .. snippet:: - :filename: django-polls/MANIFEST.in + .. code-block:: text + :caption: django-polls/MANIFEST.in include LICENSE include README.rst diff --git a/docs/intro/tutorial01.txt b/docs/intro/tutorial01.txt index aca496580e..d3d2fe3325 100644 --- a/docs/intro/tutorial01.txt +++ b/docs/intro/tutorial01.txt @@ -243,8 +243,8 @@ Write your first view Let's write the first view. Open the file ``polls/views.py`` and put the following Python code in it: -.. snippet:: - :filename: polls/views.py +.. code-block:: python + :caption: polls/views.py from django.http import HttpResponse @@ -271,8 +271,8 @@ Your app directory should now look like:: In the ``polls/urls.py`` file include the following code: -.. snippet:: - :filename: polls/urls.py +.. code-block:: python + :caption: polls/urls.py from django.urls import path @@ -286,8 +286,8 @@ The next step is to point the root URLconf at the ``polls.urls`` module. In ``mysite/urls.py``, add an import for ``django.urls.include`` and insert an :func:`~django.urls.include` in the ``urlpatterns`` list, so you have: -.. snippet:: - :filename: mysite/urls.py +.. code-block:: python + :caption: mysite/urls.py from django.contrib import admin from django.urls import include, path diff --git a/docs/intro/tutorial02.txt b/docs/intro/tutorial02.txt index c1f0aeef46..9046d167b0 100644 --- a/docs/intro/tutorial02.txt +++ b/docs/intro/tutorial02.txt @@ -135,8 +135,8 @@ with a ``Question``. These concepts are represented by simple Python classes. Edit the :file:`polls/models.py` file so it looks like this: -.. snippet:: - :filename: polls/models.py +.. code-block:: python + :caption: polls/models.py from django.db import models @@ -211,8 +211,8 @@ is ``'polls.apps.PollsConfig'``. Edit the :file:`mysite/settings.py` file and add that dotted path to the :setting:`INSTALLED_APPS` setting. It'll look like this: -.. snippet:: - :filename: mysite/settings.py +.. code-block:: python + :caption: mysite/settings.py INSTALLED_APPS = [ 'polls.apps.PollsConfig', @@ -423,8 +423,8 @@ representation of this object. Let's fix that by editing the ``Question`` model :meth:`~django.db.models.Model.__str__` method to both ``Question`` and ``Choice``: -.. snippet:: - :filename: polls/models.py +.. code-block:: python + :caption: polls/models.py from django.db import models @@ -446,8 +446,8 @@ automatically-generated admin. Note these are normal Python methods. Let's add a custom method, just for demonstration: -.. snippet:: - :filename: polls/models.py +.. code-block:: python + :caption: polls/models.py import datetime @@ -644,8 +644,8 @@ Just one thing to do: we need to tell the admin that ``Question`` objects have an admin interface. To do this, open the :file:`polls/admin.py` file, and edit it to look like this: -.. snippet:: - :filename: polls/admin.py +.. code-block:: python + :caption: polls/admin.py from django.contrib import admin diff --git a/docs/intro/tutorial03.txt b/docs/intro/tutorial03.txt index 32c0c99fd1..de84ad0612 100644 --- a/docs/intro/tutorial03.txt +++ b/docs/intro/tutorial03.txt @@ -64,8 +64,8 @@ Writing more views Now let's add a few more views to ``polls/views.py``. These views are slightly different, because they take an argument: -.. snippet:: - :filename: polls/views.py +.. code-block:: python + :caption: polls/views.py def detail(request, question_id): return HttpResponse("You're looking at question %s." % question_id) @@ -80,8 +80,8 @@ slightly different, because they take an argument: Wire these new views into the ``polls.urls`` module by adding the following :func:`~django.urls.path` calls: -.. snippet:: - :filename: polls/urls.py +.. code-block:: python + :caption: polls/urls.py from django.urls import path @@ -147,8 +147,8 @@ in :doc:`Tutorial 2 `. Here's one stab at a new ``index()`` view, which displays the latest 5 poll questions in the system, separated by commas, according to publication date: -.. snippet:: - :filename: polls/views.py +.. code-block:: python + :caption: polls/views.py from django.http import HttpResponse @@ -196,8 +196,8 @@ Django simply as ``polls/index.html``. Put the following code in that template: -.. snippet:: html+django - :filename: polls/templates/polls/index.html +.. code-block:: html+django + :caption: polls/templates/polls/index.html {% if latest_question_list %}