From 1a9098166e58704b11dcf088948efa89e088b6f5 Mon Sep 17 00:00:00 2001
From: Mariusz Felisiak <felisiak.mariusz@gmail.com>
Date: Tue, 31 May 2022 07:40:54 +0200
Subject: [PATCH] [3.2.x] Fixed docs build with sphinxcontrib-spelling 7.5.0+.

sphinxcontrib-spelling 7.5.0+ includes captions of figures in the set
of nodes for which the text is checked.

Backport of ac90529cc58507d9a07610809a795ec5fc3cbf8c from main.
---
 docs/_theme/djangodocs/static/djangodocs.css  |  1 +
 docs/howto/overriding-templates.txt           |  2 +-
 docs/howto/writing-migrations.txt             | 10 +++----
 .../writing-code/coding-style.txt             |  2 +-
 .../contributing/writing-code/unit-tests.txt  |  2 +-
 docs/internals/howto-release-django.txt       |  2 +-
 docs/intro/overview.txt                       | 14 +++++-----
 docs/intro/reusable-apps.txt                  |  8 +++---
 docs/intro/tutorial01.txt                     |  6 ++---
 docs/intro/tutorial02.txt                     | 10 +++----
 docs/intro/tutorial03.txt                     | 26 +++++++++----------
 docs/intro/tutorial04.txt                     | 14 +++++-----
 docs/intro/tutorial05.txt                     | 20 +++++++-------
 docs/intro/tutorial06.txt                     |  6 ++---
 docs/intro/tutorial07.txt                     | 18 ++++++-------
 docs/ref/contrib/admin/index.txt              | 10 +++----
 docs/ref/contrib/admin/javascript.txt         |  4 +--
 docs/ref/databases.txt                        |  2 +-
 docs/ref/models/expressions.txt               |  2 +-
 docs/ref/models/fields.txt                    |  4 +--
 docs/ref/templates/language.txt               |  8 +++---
 docs/releases/1.9.txt                         |  8 +++---
 docs/topics/auth/passwords.txt                |  6 ++---
 .../class-based-views/generic-editing.txt     | 14 +++++-----
 docs/topics/class-based-views/mixins.txt      |  4 +--
 docs/topics/db/models.txt                     |  2 +-
 docs/topics/forms/index.txt                   |  8 +++---
 docs/topics/http/file-uploads.txt             |  8 +++---
 docs/topics/http/urls.txt                     |  8 +++---
 docs/topics/logging.txt                       | 10 +++----
 docs/topics/testing/advanced.txt              |  8 +++---
 31 files changed, 124 insertions(+), 123 deletions(-)

diff --git a/docs/_theme/djangodocs/static/djangodocs.css b/docs/_theme/djangodocs/static/djangodocs.css
index bd47749a06a..0b6a8b9ad3b 100644
--- a/docs/_theme/djangodocs/static/djangodocs.css
+++ b/docs/_theme/djangodocs/static/djangodocs.css
@@ -103,6 +103,7 @@ dt .literal, table .literal { background:none; }
 #bd a.reference { text-decoration: none; }
 #bd a.reference tt.literal { border-bottom: 1px #234f32 dotted; }
 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.code-block-caption .literal {color: white; }
 div.literal-block-wrapper pre { margin-top: 0; }
 
 /* Restore colors of pygments hyperlinked code */
diff --git a/docs/howto/overriding-templates.txt b/docs/howto/overriding-templates.txt
index 0f880690698..55d7c66f426 100644
--- a/docs/howto/overriding-templates.txt
+++ b/docs/howto/overriding-templates.txt
@@ -112,7 +112,7 @@ For example, you can use this technique to add a custom logo to the
 ``admin/base_site.html`` template:
 
     .. code-block:: html+django
-       :caption: templates/admin/base_site.html
+       :caption: ``templates/admin/base_site.html``
 
         {% extends "admin/base_site.html" %}
 
diff --git a/docs/howto/writing-migrations.txt b/docs/howto/writing-migrations.txt
index 00dc0dfadfa..3c571fdc94d 100644
--- a/docs/howto/writing-migrations.txt
+++ b/docs/howto/writing-migrations.txt
@@ -40,7 +40,7 @@ You can also provide hints that will be passed to the :meth:`allow_migrate()`
 method of database routers as ``**hints``:
 
 .. code-block:: python
-    :caption: myapp/dbrouters.py
+    :caption: ``myapp/dbrouters.py``
 
     class MyRouter:
 
@@ -98,7 +98,7 @@ the respective field according to your needs.
   ``AlterField``, and add imports of ``uuid`` and ``models``. For example:
 
   .. code-block:: python
-    :caption: 0006_remove_uuid_null.py
+    :caption: ``0006_remove_uuid_null.py``
 
     # Generated by Django A.B on YYYY-MM-DD HH:MM
     from django.db import migrations, models
@@ -122,7 +122,7 @@ the respective field according to your needs.
   similar to this:
 
   .. code-block:: python
-    :caption: 0004_add_uuid_field.py
+    :caption: ``0004_add_uuid_field.py``
 
     class Migration(migrations.Migration):
 
@@ -149,7 +149,7 @@ the respective field according to your needs.
   of ``uuid``. For example:
 
   .. code-block:: python
-    :caption: 0005_populate_uuid_values.py
+    :caption: ``0005_populate_uuid_values.py``
 
     # Generated by Django A.B on YYYY-MM-DD HH:MM
     from django.db import migrations
@@ -283,7 +283,7 @@ project anywhere without first installing and then uninstalling the old app.
 Here's a sample migration:
 
 .. code-block:: python
-    :caption: myapp/migrations/0124_move_old_app_to_new_app.py
+    :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 3c82aa20deb..61a350821e5 100644
--- a/docs/internals/contributing/writing-code/coding-style.txt
+++ b/docs/internals/contributing/writing-code/coding-style.txt
@@ -186,7 +186,7 @@ Imports
   For example (comments are for explanatory purposes only):
 
   .. code-block:: python
-      :caption: django/contrib/admin/example.py
+      :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 490a4673b69..bd426099d6d 100644
--- a/docs/internals/contributing/writing-code/unit-tests.txt
+++ b/docs/internals/contributing/writing-code/unit-tests.txt
@@ -557,7 +557,7 @@ Since this pattern involves a lot of boilerplate, Django provides the
     installed, you should pass the set of targeted ``app_label`` as arguments:
 
     .. code-block:: python
-        :caption: tests/app_label/tests.py
+        :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 beb3581d54f..723804a95e3 100644
--- a/docs/internals/howto-release-django.txt
+++ b/docs/internals/howto-release-django.txt
@@ -63,7 +63,7 @@ You'll need a few things before getting started:
 * Access to Django's record on PyPI. Create a file with your credentials:
 
   .. code-block:: ini
-    :caption: ~/.pypirc
+    :caption: ``~/.pypirc``
 
     [pypi]
     username:YourUsername
diff --git a/docs/intro/overview.txt b/docs/intro/overview.txt
index c0d528527f7..86b172f526f 100644
--- a/docs/intro/overview.txt
+++ b/docs/intro/overview.txt
@@ -26,7 +26,7 @@ representing your models -- so far, it's been solving many years' worth of
 database-schema problems. Here's a quick example:
 
 .. code-block:: python
-    :caption: mysite/news/models.py
+    :caption: ``mysite/news/models.py``
 
     from django.db import models
 
@@ -146,7 +146,7 @@ a website that lets authenticated users add, change and delete objects. The
 only step required is to register your model in the admin site:
 
 .. code-block:: python
-    :caption: mysite/news/models.py
+    :caption: ``mysite/news/models.py``
 
     from django.db import models
 
@@ -157,7 +157,7 @@ only step required is to register your model in the admin site:
         reporter = models.ForeignKey(Reporter, on_delete=models.CASCADE)
 
 .. code-block:: python
-    :caption: mysite/news/admin.py
+    :caption: ``mysite/news/admin.py``
 
     from django.contrib import admin
 
@@ -189,7 +189,7 @@ Here's what a URLconf might look like for the ``Reporter``/``Article``
 example above:
 
 .. code-block:: python
-    :caption: mysite/news/urls.py
+    :caption: ``mysite/news/urls.py``
 
     from django.urls import path
 
@@ -229,7 +229,7 @@ and renders the template with the retrieved data. Here's an example view for
 ``year_archive`` from above:
 
 .. code-block:: python
-    :caption: mysite/news/views.py
+    :caption: ``mysite/news/views.py``
 
     from django.shortcuts import render
 
@@ -258,7 +258,7 @@ Let's say the ``news/year_archive.html`` template was found. Here's what that
 might look like:
 
 .. code-block:: html+django
-    :caption: mysite/news/templates/news/year_archive.html
+    :caption: ``mysite/news/templates/news/year_archive.html``
 
     {% extends "base.html" %}
 
@@ -299,7 +299,7 @@ Here's what the "base.html" template, including the use of :doc:`static files
 </howto/static-files/index>`, might look like:
 
 .. code-block:: html+django
-    :caption: mysite/templates/base.html
+    :caption: ``mysite/templates/base.html``
 
     {% load static %}
     <html>
diff --git a/docs/intro/reusable-apps.txt b/docs/intro/reusable-apps.txt
index d00879ea603..82bdaf27845 100644
--- a/docs/intro/reusable-apps.txt
+++ b/docs/intro/reusable-apps.txt
@@ -144,7 +144,7 @@ this. For a small app like polls, this process isn't too difficult.
 #. Create a file ``django-polls/README.rst`` with the following contents:
 
    .. code-block:: rst
-       :caption: django-polls/README.rst
+       :caption: ``django-polls/README.rst``
 
        =====
        Polls
@@ -191,7 +191,7 @@ this. For a small app like polls, this process isn't too difficult.
    with the following contents:
 
    .. code-block:: ini
-        :caption: django-polls/setup.cfg
+        :caption: ``django-polls/setup.cfg``
 
         [metadata]
         name = django-polls
@@ -226,7 +226,7 @@ this. For a small app like polls, this process isn't too difficult.
             Django >= X.Y  # Replace "X.Y" as appropriate
 
    .. code-block:: python
-        :caption: django-polls/setup.py
+        :caption: ``django-polls/setup.py``
 
         from setuptools import setup
 
@@ -240,7 +240,7 @@ this. For a small app like polls, this process isn't too difficult.
    contents:
 
    .. code-block:: text
-       :caption: django-polls/MANIFEST.in
+       :caption: ``django-polls/MANIFEST.in``
 
        include LICENSE
        include README.rst
diff --git a/docs/intro/tutorial01.txt b/docs/intro/tutorial01.txt
index 05f99b6f761..f3b080e9bb1 100644
--- a/docs/intro/tutorial01.txt
+++ b/docs/intro/tutorial01.txt
@@ -245,7 +245,7 @@ Let's write the first view. Open the file ``polls/views.py``
 and put the following Python code in it:
 
 .. code-block:: python
-    :caption: polls/views.py
+    :caption: ``polls/views.py``
 
     from django.http import HttpResponse
 
@@ -273,7 +273,7 @@ Your app directory should now look like::
 In the ``polls/urls.py`` file include the following code:
 
 .. code-block:: python
-    :caption: polls/urls.py
+    :caption: ``polls/urls.py``
 
     from django.urls import path
 
@@ -288,7 +288,7 @@ The next step is to point the root URLconf at the ``polls.urls`` module. In
 :func:`~django.urls.include` in the ``urlpatterns`` list, so you have:
 
 .. code-block:: python
-    :caption: mysite/urls.py
+    :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 b315027c5de..2fa780178ae 100644
--- a/docs/intro/tutorial02.txt
+++ b/docs/intro/tutorial02.txt
@@ -141,7 +141,7 @@ These concepts are represented by Python classes. Edit the
 :file:`polls/models.py` file so it looks like this:
 
 .. code-block:: python
-    :caption: polls/models.py
+    :caption: ``polls/models.py``
 
     from django.db import models
 
@@ -217,7 +217,7 @@ add that dotted path to the :setting:`INSTALLED_APPS` setting. It'll look like
 this:
 
 .. code-block:: python
-    :caption: mysite/settings.py
+    :caption: ``mysite/settings.py``
 
     INSTALLED_APPS = [
         'polls.apps.PollsConfig',
@@ -424,7 +424,7 @@ representation of this object. Let's fix that by editing the ``Question`` model
 ``Choice``:
 
 .. code-block:: python
-    :caption: polls/models.py
+    :caption: ``polls/models.py``
 
     from django.db import models
 
@@ -448,7 +448,7 @@ automatically-generated admin.
 Let's also add a custom method to this model:
 
 .. code-block:: python
-    :caption: polls/models.py
+    :caption: ``polls/models.py``
 
     import datetime
 
@@ -646,7 +646,7 @@ have an admin interface. To do this, open the :file:`polls/admin.py` file, and
 edit it to look like this:
 
 .. code-block:: python
-    :caption: polls/admin.py
+    :caption: ``polls/admin.py``
 
     from django.contrib import admin
 
diff --git a/docs/intro/tutorial03.txt b/docs/intro/tutorial03.txt
index 82fa35e4970..720a83a3e50 100644
--- a/docs/intro/tutorial03.txt
+++ b/docs/intro/tutorial03.txt
@@ -70,7 +70,7 @@ Now let's add a few more views to ``polls/views.py``. These views are
 slightly different, because they take an argument:
 
 .. code-block:: python
-    :caption: polls/views.py
+    :caption: ``polls/views.py``
 
     def detail(request, question_id):
         return HttpResponse("You're looking at question %s." % question_id)
@@ -86,7 +86,7 @@ Wire these new views into the ``polls.urls`` module by adding the following
 :func:`~django.urls.path` calls:
 
 .. code-block:: python
-    :caption: polls/urls.py
+    :caption: ``polls/urls.py``
 
     from django.urls import path
 
@@ -147,7 +147,7 @@ view, which displays the latest 5 poll questions in the system, separated by
 commas, according to publication date:
 
 .. code-block:: python
-    :caption: polls/views.py
+    :caption: ``polls/views.py``
 
     from django.http import HttpResponse
 
@@ -196,7 +196,7 @@ Django as ``polls/index.html``.
 Put the following code in that template:
 
 .. code-block:: html+django
-    :caption: polls/templates/polls/index.html
+    :caption: ``polls/templates/polls/index.html``
 
     {% if latest_question_list %}
         <ul>
@@ -218,7 +218,7 @@ __ https://developer.mozilla.org/en-US/docs/Learn/HTML/Introduction_to_HTML/Gett
 Now let's update our ``index`` view in ``polls/views.py`` to use the template:
 
 .. code-block:: python
-    :caption: polls/views.py
+    :caption: ``polls/views.py``
 
     from django.http import HttpResponse
     from django.template import loader
@@ -251,7 +251,7 @@ template. Django provides a shortcut. Here's the full ``index()`` view,
 rewritten:
 
 .. code-block:: python
-    :caption: polls/views.py
+    :caption: ``polls/views.py``
 
     from django.shortcuts import render
 
@@ -280,7 +280,7 @@ Now, let's tackle the question detail view -- the page that displays the questio
 for a given poll. Here's the view:
 
 .. code-block:: python
-    :caption: polls/views.py
+    :caption: ``polls/views.py``
 
     from django.http import Http404
     from django.shortcuts import render
@@ -302,7 +302,7 @@ later, but if you'd like to quickly get the above example working, a file
 containing just:
 
 .. code-block:: html+django
-    :caption: polls/templates/polls/detail.html
+    :caption: ``polls/templates/polls/detail.html``
 
     {{ question }}
 
@@ -316,7 +316,7 @@ and raise :exc:`~django.http.Http404` if the object doesn't exist. Django
 provides a shortcut. Here's the ``detail()`` view, rewritten:
 
 .. code-block:: python
-    :caption: polls/views.py
+    :caption: ``polls/views.py``
 
     from django.shortcuts import get_object_or_404, render
 
@@ -358,7 +358,7 @@ variable ``question``, here's what the ``polls/detail.html`` template might look
 like:
 
 .. code-block:: html+django
-    :caption: polls/templates/polls/detail.html
+    :caption: ``polls/templates/polls/detail.html``
 
     <h1>{{ question.question_text }}</h1>
     <ul>
@@ -432,7 +432,7 @@ The answer is to add namespaces to your  URLconf. In the ``polls/urls.py``
 file, go ahead and add an ``app_name`` to set the application namespace:
 
 .. code-block:: python
-    :caption: polls/urls.py
+    :caption: ``polls/urls.py``
 
     from django.urls import path
 
@@ -449,14 +449,14 @@ file, go ahead and add an ``app_name`` to set the application namespace:
 Now change your ``polls/index.html`` template from:
 
 .. code-block:: html+django
-    :caption: polls/templates/polls/index.html
+    :caption: ``polls/templates/polls/index.html``
 
     <li><a href="{% url 'detail' question.id %}">{{ question.question_text }}</a></li>
 
 to point at the namespaced detail view:
 
 .. code-block:: html+django
-    :caption: polls/templates/polls/index.html
+    :caption: ``polls/templates/polls/index.html``
 
     <li><a href="{% url 'polls:detail' question.id %}">{{ question.question_text }}</a></li>
 
diff --git a/docs/intro/tutorial04.txt b/docs/intro/tutorial04.txt
index 4dae8892ae9..98494a9ab30 100644
--- a/docs/intro/tutorial04.txt
+++ b/docs/intro/tutorial04.txt
@@ -18,7 +18,7 @@ Let's update our poll detail template ("polls/detail.html") from the last
 tutorial, so that the template contains an HTML ``<form>`` element:
 
 .. code-block:: html+django
-    :caption: polls/templates/polls/detail.html
+    :caption: ``polls/templates/polls/detail.html``
 
     <form action="{% url 'polls:vote' question.id %}" method="post">
     {% csrf_token %}
@@ -64,7 +64,7 @@ something with it. Remember, in :doc:`Tutorial 3 </intro/tutorial03>`, we
 created a URLconf for the polls application that includes this line:
 
 .. code-block:: python
-    :caption: polls/urls.py
+    :caption: ``polls/urls.py``
 
     path('<int:question_id>/vote/', views.vote, name='vote'),
 
@@ -72,7 +72,7 @@ We also created a dummy implementation of the ``vote()`` function. Let's
 create a real version. Add the following to ``polls/views.py``:
 
 .. code-block:: python
-    :caption: polls/views.py
+    :caption: ``polls/views.py``
 
     from django.http import HttpResponse, HttpResponseRedirect
     from django.shortcuts import get_object_or_404, render
@@ -152,7 +152,7 @@ After somebody votes in a question, the ``vote()`` view redirects to the results
 page for the question. Let's write that view:
 
 .. code-block:: python
-    :caption: polls/views.py
+    :caption: ``polls/views.py``
 
     from django.shortcuts import get_object_or_404, render
 
@@ -168,7 +168,7 @@ redundancy later.
 Now, create a ``polls/results.html`` template:
 
 .. code-block:: html+django
-    :caption: polls/templates/polls/results.html
+    :caption: ``polls/templates/polls/results.html``
 
     <h1>{{ question.question_text }}</h1>
 
@@ -240,7 +240,7 @@ Amend URLconf
 First, open the ``polls/urls.py`` URLconf and change it like so:
 
 .. code-block:: python
-    :caption: polls/urls.py
+    :caption: ``polls/urls.py``
 
     from django.urls import path
 
@@ -265,7 +265,7 @@ views and use Django's generic views instead. To do so, open the
 ``polls/views.py`` file and change it like so:
 
 .. code-block:: python
-    :caption: polls/views.py
+    :caption: ``polls/views.py``
 
     from django.http import HttpResponseRedirect
     from django.shortcuts import get_object_or_404, render
diff --git a/docs/intro/tutorial05.txt b/docs/intro/tutorial05.txt
index d7f6334324d..4f21f2b7d10 100644
--- a/docs/intro/tutorial05.txt
+++ b/docs/intro/tutorial05.txt
@@ -172,7 +172,7 @@ whose name begins with ``test``.
 Put the following in the ``tests.py`` file in the ``polls`` application:
 
 .. code-block:: python
-    :caption: polls/tests.py
+    :caption: ``polls/tests.py``
 
     import datetime
 
@@ -261,7 +261,7 @@ return ``False`` if its ``pub_date`` is in the future. Amend the method in
 past:
 
 .. code-block:: python
-    :caption: polls/models.py
+    :caption: ``polls/models.py``
 
     def was_published_recently(self):
         now = timezone.now()
@@ -297,7 +297,7 @@ Add two more test methods to the same class, to test the behavior of the method
 more comprehensively:
 
 .. code-block:: python
-    :caption: polls/tests.py
+    :caption: ``polls/tests.py``
 
     def test_was_published_recently_with_old_question(self):
         """
@@ -413,7 +413,7 @@ In :doc:`Tutorial 4 </intro/tutorial04>` we introduced a class-based view,
 based on :class:`~django.views.generic.list.ListView`:
 
 .. code-block:: python
-    :caption: polls/views.py
+    :caption: ``polls/views.py``
 
     class IndexView(generic.ListView):
         template_name = 'polls/index.html'
@@ -428,14 +428,14 @@ checks the date by comparing it with ``timezone.now()``. First we need to add
 an import:
 
 .. code-block:: python
-    :caption: polls/views.py
+    :caption: ``polls/views.py``
 
     from django.utils import timezone
 
 and then we must amend the ``get_queryset`` method like so:
 
 .. code-block:: python
-    :caption: polls/views.py
+    :caption: ``polls/views.py``
 
     def get_queryset(self):
         """
@@ -463,7 +463,7 @@ our :djadmin:`shell` session above.
 Add the following to ``polls/tests.py``:
 
 .. code-block:: python
-    :caption: polls/tests.py
+    :caption: ``polls/tests.py``
 
     from django.urls import reverse
 
@@ -471,7 +471,7 @@ and we'll create a shortcut function to create questions as well as a new test
 class:
 
 .. code-block:: python
-    :caption: polls/tests.py
+    :caption: ``polls/tests.py``
 
     def create_question(question_text, days):
         """
@@ -572,7 +572,7 @@ the *index*, users can still reach them if they know or guess the right URL. So
 we need to add a similar  constraint to ``DetailView``:
 
 .. code-block:: python
-    :caption: polls/views.py
+    :caption: ``polls/views.py``
 
     class DetailView(generic.DetailView):
         ...
@@ -587,7 +587,7 @@ is in the past can be displayed, and that one with a ``pub_date`` in the future
 is not:
 
 .. code-block:: python
-    :caption: polls/tests.py
+    :caption: ``polls/tests.py``
 
     class QuestionDetailViewTests(TestCase):
         def test_future_question(self):
diff --git a/docs/intro/tutorial06.txt b/docs/intro/tutorial06.txt
index be69f5e162b..2ebb208bcaa 100644
--- a/docs/intro/tutorial06.txt
+++ b/docs/intro/tutorial06.txt
@@ -61,7 +61,7 @@ the path for templates.
 Put the following code in that stylesheet (``polls/static/polls/style.css``):
 
 .. code-block:: css
-    :caption: polls/static/polls/style.css
+    :caption: ``polls/static/polls/style.css``
 
     li a {
         color: green;
@@ -70,7 +70,7 @@ Put the following code in that stylesheet (``polls/static/polls/style.css``):
 Next, add the following at the top of ``polls/templates/polls/index.html``:
 
 .. code-block:: html+django
-    :caption: polls/templates/polls/index.html
+    :caption: ``polls/templates/polls/index.html``
 
     {% load static %}
 
@@ -101,7 +101,7 @@ called ``background.gif``. In other words, put your image in
 Then, add to your stylesheet (``polls/static/polls/style.css``):
 
 .. code-block:: css
-    :caption: polls/static/polls/style.css
+    :caption: ``polls/static/polls/style.css``
 
     body {
         background: white url("images/background.gif") no-repeat;
diff --git a/docs/intro/tutorial07.txt b/docs/intro/tutorial07.txt
index f80b6fc6c38..f93ba18d992 100644
--- a/docs/intro/tutorial07.txt
+++ b/docs/intro/tutorial07.txt
@@ -24,7 +24,7 @@ Let's see how this works by reordering the fields on the edit form. Replace
 the ``admin.site.register(Question)`` line with:
 
 .. code-block:: python
-    :caption: polls/admin.py
+    :caption: ``polls/admin.py``
 
     from django.contrib import admin
 
@@ -53,7 +53,7 @@ And speaking of forms with dozens of fields, you might want to split the form
 up into fieldsets:
 
 .. code-block:: python
-    :caption: polls/admin.py
+    :caption: ``polls/admin.py``
 
     from django.contrib import admin
 
@@ -87,7 +87,7 @@ There are two ways to solve this problem. The first is to register ``Choice``
 with the admin just as we did with ``Question``:
 
 .. code-block:: python
-    :caption: polls/admin.py
+    :caption: ``polls/admin.py``
 
     from django.contrib import admin
 
@@ -121,7 +121,7 @@ Remove the ``register()`` call for the ``Choice`` model. Then, edit the ``Questi
 registration code to read:
 
 .. code-block:: python
-    :caption: polls/admin.py
+    :caption: ``polls/admin.py``
 
     from django.contrib import admin
 
@@ -168,7 +168,7 @@ tabular way of displaying inline related objects. To use it, change the
 ``ChoiceInline`` declaration to read:
 
 .. code-block:: python
-    :caption: polls/admin.py
+    :caption: ``polls/admin.py``
 
     class ChoiceInline(admin.TabularInline):
         #...
@@ -200,7 +200,7 @@ tuple of field names to display, as columns, on the change list page for the
 object:
 
 .. code-block:: python
-    :caption: polls/admin.py
+    :caption: ``polls/admin.py``
 
     class QuestionAdmin(admin.ModelAdmin):
         # ...
@@ -210,7 +210,7 @@ For good measure, let's also include the ``was_published_recently()`` method
 from :doc:`Tutorial 2 </intro/tutorial02>`:
 
 .. code-block:: python
-    :caption: polls/admin.py
+    :caption: ``polls/admin.py``
 
     class QuestionAdmin(admin.ModelAdmin):
         # ...
@@ -232,7 +232,7 @@ You can improve that by using the :func:`~django.contrib.admin.display`
 decorator on that method (in :file:`polls/models.py`), as follows:
 
 .. code-block:: python
-    :caption: polls/models.py
+    :caption: ``polls/models.py``
 
     from django.contrib import admin
 
@@ -310,7 +310,7 @@ Open your settings file (:file:`mysite/settings.py`, remember) and add a
 :setting:`DIRS <TEMPLATES-DIRS>` option in the :setting:`TEMPLATES` setting:
 
 .. code-block:: python
-    :caption: mysite/settings.py
+    :caption: ``mysite/settings.py``
 
     TEMPLATES = [
         {
diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt
index 4bafc5e1b85..7a51d110611 100644
--- a/docs/ref/contrib/admin/index.txt
+++ b/docs/ref/contrib/admin/index.txt
@@ -3093,7 +3093,7 @@ it instead of with the default site. Finally, update :file:`myproject/urls.py`
 to reference your :class:`AdminSite` subclass.
 
 .. code-block:: python
-    :caption: myapp/admin.py
+    :caption: ``myapp/admin.py``
 
     from django.contrib.admin import AdminSite
 
@@ -3107,7 +3107,7 @@ to reference your :class:`AdminSite` subclass.
 
 
 .. code-block:: python
-    :caption: myproject/urls.py
+    :caption: ``myproject/urls.py``
 
     from django.urls import path
 
@@ -3134,7 +3134,7 @@ to the dotted import path of either a ``AdminSite`` subclass or a callable that
 returns a site instance.
 
 .. code-block:: python
-    :caption: myproject/admin.py
+    :caption: ``myproject/admin.py``
 
     from django.contrib import admin
 
@@ -3142,7 +3142,7 @@ returns a site instance.
         ...
 
 .. code-block:: python
-    :caption: myproject/apps.py
+    :caption: ``myproject/apps.py``
 
     from django.contrib.admin.apps import AdminConfig
 
@@ -3150,7 +3150,7 @@ returns a site instance.
         default_site = 'myproject.admin.MyAdminSite'
 
 .. code-block:: python
-    :caption: myproject/settings.py
+    :caption: ``myproject/settings.py``
 
     INSTALLED_APPS = [
         ...
diff --git a/docs/ref/contrib/admin/javascript.txt b/docs/ref/contrib/admin/javascript.txt
index 05731c57b0f..9645f6abbcf 100644
--- a/docs/ref/contrib/admin/javascript.txt
+++ b/docs/ref/contrib/admin/javascript.txt
@@ -32,7 +32,7 @@ In your custom ``change_form.html`` template, extend the
     {% endblock %}
 
 .. code-block:: javascript
-    :caption: app/static/app/formset_handlers.js
+    :caption: ``app/static/app/formset_handlers.js``
 
     (function($) {
         $(document).on('formset:added', function(event, $row, formsetName) {
@@ -70,7 +70,7 @@ listen to the event triggered from there. For example:
     {% endblock %}
 
 .. code-block:: javascript
-    :caption: app/static/app/unregistered_handlers.js
+    :caption: ``app/static/app/unregistered_handlers.js``
 
     django.jQuery(document).on('formset:added', function(event, $row, formsetName) {
         // Row added
diff --git a/docs/ref/databases.txt b/docs/ref/databases.txt
index 89341ad798c..24aa7324626 100644
--- a/docs/ref/databases.txt
+++ b/docs/ref/databases.txt
@@ -1033,7 +1033,7 @@ example of subclassing the PostgreSQL engine to change a feature class
 ``allows_group_by_selected_pks_on_model``:
 
 .. code-block:: python
-    :caption: mysite/mydbengine/base.py
+    :caption: ``mysite/mydbengine/base.py``
 
     from django.db.backends.postgresql import base, features
 
diff --git a/docs/ref/models/expressions.txt b/docs/ref/models/expressions.txt
index 236918380ee..e84a729f6e1 100644
--- a/docs/ref/models/expressions.txt
+++ b/docs/ref/models/expressions.txt
@@ -327,7 +327,7 @@ The ``Func`` API is as follows:
         customize the SQL as needed. For example:
 
         .. code-block:: python
-            :caption: django/db/models/functions.py
+            :caption: ``django/db/models/functions.py``
 
             class ConcatPair(Func):
                 ...
diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt
index 3d671a9aacb..62954b1f488 100644
--- a/docs/ref/models/fields.txt
+++ b/docs/ref/models/fields.txt
@@ -1478,7 +1478,7 @@ Relationships defined this way on :ref:`abstract models
 concrete model and are not relative to the abstract model's ``app_label``:
 
 .. code-block:: python
-    :caption: products/models.py
+    :caption: ``products/models.py``
 
     from django.db import models
 
@@ -1489,7 +1489,7 @@ concrete model and are not relative to the abstract model's ``app_label``:
             abstract = True
 
 .. code-block:: python
-    :caption: production/models.py
+    :caption: ``production/models.py``
 
     from django.db import models
     from products.models import AbstractCar
diff --git a/docs/ref/templates/language.txt b/docs/ref/templates/language.txt
index 04b363c0cfd..cc627373b21 100644
--- a/docs/ref/templates/language.txt
+++ b/docs/ref/templates/language.txt
@@ -564,7 +564,7 @@ current one as well as templates included via the :ttag:`include` tag,
 just like all block tags. For example:
 
 .. code-block:: html+django
-    :caption: base.html
+    :caption: ``base.html``
 
     {% autoescape off %}
     <h1>{% block title %}{% endblock %}</h1>
@@ -573,7 +573,7 @@ just like all block tags. For example:
     {% endautoescape %}
 
 .. code-block:: html+django
-    :caption: child.html
+    :caption: ``child.html``
 
     {% extends "base.html" %}
     {% block title %}This &amp; that{% endblock %}
@@ -653,14 +653,14 @@ of all comments related to the current task with::
 You can also access methods you've explicitly defined on your own models:
 
 .. code-block:: python
-    :caption: models.py
+    :caption: ``models.py``
 
     class Task(models.Model):
         def foo(self):
             return "bar"
 
 .. code-block:: html+django
-    :caption: template.html
+    :caption: ``template.html``
 
     {{ task.foo }}
 
diff --git a/docs/releases/1.9.txt b/docs/releases/1.9.txt
index 07a75fc005e..b6579ee66b5 100644
--- a/docs/releases/1.9.txt
+++ b/docs/releases/1.9.txt
@@ -1264,7 +1264,7 @@ attribute (as below). If the ``app_name`` is set in this new way, the
 ``app_name``. For example, the URL patterns in the tutorial are changed from:
 
 .. code-block:: python
-    :caption: mysite/urls.py
+    :caption: ``mysite/urls.py``
 
     urlpatterns = [
         url(r'^polls/', include('polls.urls', namespace="polls")),
@@ -1274,7 +1274,7 @@ attribute (as below). If the ``app_name`` is set in this new way, the
 to:
 
 .. code-block:: python
-    :caption: mysite/urls.py
+    :caption: ``mysite/urls.py``
 
     urlpatterns = [
         url(r'^polls/', include('polls.urls')),  # 'namespace="polls"' removed
@@ -1282,7 +1282,7 @@ to:
     ]
 
 .. code-block:: python
-    :caption: polls/urls.py
+    :caption: ``polls/urls.py``
 
     app_name = 'polls'  # added
     urlpatterns = [...]
@@ -1292,7 +1292,7 @@ is deprecated. Instead, pass ``admin.site.urls`` directly to
 ``django.conf.urls.url()``:
 
 .. code-block:: python
-    :caption: urls.py
+    :caption: ``urls.py``
 
     from django.conf.urls import url
     from django.contrib import admin
diff --git a/docs/topics/auth/passwords.txt b/docs/topics/auth/passwords.txt
index 8fc4ba6ed41..acda0fff342 100644
--- a/docs/topics/auth/passwords.txt
+++ b/docs/topics/auth/passwords.txt
@@ -274,7 +274,7 @@ modify the pattern to work with any algorithm or with a custom user model.
 First, we'll add the custom hasher:
 
 .. code-block:: python
-    :caption: accounts/hashers.py
+    :caption: ``accounts/hashers.py``
 
     from django.contrib.auth.hashers import (
         PBKDF2PasswordHasher, SHA1PasswordHasher,
@@ -294,7 +294,7 @@ First, we'll add the custom hasher:
 The data migration might look something like:
 
 .. code-block:: python
-    :caption: accounts/migrations/0002_migrate_sha1_passwords.py
+    :caption: ``accounts/migrations/0002_migrate_sha1_passwords.py``
 
     from django.db import migrations
 
@@ -329,7 +329,7 @@ several thousand users, depending on the speed of your hardware.
 Finally, we'll add a :setting:`PASSWORD_HASHERS` setting:
 
 .. code-block:: python
-    :caption: mysite/settings.py
+    :caption: ``mysite/settings.py``
 
     PASSWORD_HASHERS = [
         'django.contrib.auth.hashers.PBKDF2PasswordHasher',
diff --git a/docs/topics/class-based-views/generic-editing.txt b/docs/topics/class-based-views/generic-editing.txt
index 5bc56b84e13..b40d3068989 100644
--- a/docs/topics/class-based-views/generic-editing.txt
+++ b/docs/topics/class-based-views/generic-editing.txt
@@ -19,7 +19,7 @@ Basic forms
 Given a contact form:
 
 .. code-block:: python
-    :caption: forms.py
+    :caption: ``forms.py``
 
     from django import forms
 
@@ -34,7 +34,7 @@ Given a contact form:
 The view can be constructed using a ``FormView``:
 
 .. code-block:: python
-    :caption: views.py
+    :caption: ``views.py``
 
     from myapp.forms import ContactForm
     from django.views.generic.edit import FormView
@@ -97,7 +97,7 @@ First we need to add :meth:`~django.db.models.Model.get_absolute_url()` to our
 ``Author`` class:
 
 .. code-block:: python
-    :caption: models.py
+    :caption: ``models.py``
 
     from django.db import models
     from django.urls import reverse
@@ -113,7 +113,7 @@ work. Notice how we're just configuring the generic class-based views
 here; we don't have to write any logic ourselves:
 
 .. code-block:: python
-    :caption: views.py
+    :caption: ``views.py``
 
     from django.urls import reverse_lazy
     from django.views.generic.edit import CreateView, DeleteView, UpdateView
@@ -147,7 +147,7 @@ and :attr:`~django.views.generic.edit.FormMixin.form_class` attributes, an
 Finally, we hook these new views into the URLconf:
 
 .. code-block:: python
-    :caption: urls.py
+    :caption: ``urls.py``
 
     from django.urls import path
     from myapp.views import AuthorCreateView, AuthorDeleteView, AuthorUpdateView
@@ -188,7 +188,7 @@ you can use a custom :class:`~django.forms.ModelForm` to do this. First, add
 the foreign key relation to the model:
 
 .. code-block:: python
-    :caption: models.py
+    :caption: ``models.py``
 
     from django.contrib.auth.models import User
     from django.db import models
@@ -204,7 +204,7 @@ to edit, and override
 :meth:`~django.views.generic.edit.ModelFormMixin.form_valid()` to add the user:
 
 .. code-block:: python
-    :caption: views.py
+    :caption: ``views.py``
 
     from django.contrib.auth.mixins import LoginRequiredMixin
     from django.views.generic.edit import CreateView
diff --git a/docs/topics/class-based-views/mixins.txt b/docs/topics/class-based-views/mixins.txt
index 7b193ea7f03..5f42cedd70c 100644
--- a/docs/topics/class-based-views/mixins.txt
+++ b/docs/topics/class-based-views/mixins.txt
@@ -221,7 +221,7 @@ We'll demonstrate this with the ``Author`` model we used in the
 :doc:`generic class-based views introduction<generic-display>`.
 
 .. code-block:: python
-    :caption: views.py
+    :caption: ``views.py``
 
     from django.http import HttpResponseForbidden, HttpResponseRedirect
     from django.urls import reverse
@@ -253,7 +253,7 @@ look up the author we're interested in, which it does with a call to
 We can hook this into our URLs easily enough:
 
 .. code-block:: python
-    :caption: urls.py
+    :caption: ``urls.py``
 
     from django.urls import path
     from books.views import RecordInterestView
diff --git a/docs/topics/db/models.txt b/docs/topics/db/models.txt
index 26a6d7dc587..04721126f49 100644
--- a/docs/topics/db/models.txt
+++ b/docs/topics/db/models.txt
@@ -1472,7 +1472,7 @@ For example, if you had ``organic.py`` and ``synthetic.py`` in the ``models``
 directory:
 
 .. code-block:: python
-    :caption: myapp/models/__init__.py
+    :caption: ``myapp/models/__init__.py``
 
     from .organic import Person
     from .synthetic import Robot
diff --git a/docs/topics/forms/index.txt b/docs/topics/forms/index.txt
index e55b6d7bf22..aefccb0fea8 100644
--- a/docs/topics/forms/index.txt
+++ b/docs/topics/forms/index.txt
@@ -227,7 +227,7 @@ We already know what we want our HTML form to look like. Our starting point for
 it in Django is this:
 
 .. code-block:: python
-    :caption: forms.py
+    :caption: ``forms.py``
 
     from django import forms
 
@@ -277,7 +277,7 @@ To handle the form we need to instantiate it in the view for the URL where we
 want it to be published:
 
 .. code-block:: python
-    :caption: views.py
+    :caption: ``views.py``
 
     from django.http import HttpResponseRedirect
     from django.shortcuts import render
@@ -404,7 +404,7 @@ Consider a more useful form than our minimal example above, which we could use
 to implement "contact me" functionality on a personal website:
 
 .. code-block:: python
-    :caption: forms.py
+    :caption: ``forms.py``
 
     from django import forms
 
@@ -453,7 +453,7 @@ values to a Python ``int`` and ``float`` respectively.
 Here's how the form data could be processed in the view that handles this form:
 
 .. code-block:: python
-    :caption: views.py
+    :caption: ``views.py``
 
     from django.core.mail import send_mail
 
diff --git a/docs/topics/http/file-uploads.txt b/docs/topics/http/file-uploads.txt
index ca272d785a5..7ba6db00bf7 100644
--- a/docs/topics/http/file-uploads.txt
+++ b/docs/topics/http/file-uploads.txt
@@ -22,7 +22,7 @@ Basic file uploads
 Consider a form containing a :class:`~django.forms.FileField`:
 
 .. code-block:: python
-    :caption: forms.py
+    :caption: ``forms.py``
 
     from django import forms
 
@@ -46,7 +46,7 @@ Most of the time, you'll pass the file data from ``request`` into the form as
 described in :ref:`binding-uploaded-files`. This would look something like:
 
 .. code-block:: python
-    :caption: views.py
+    :caption: ``views.py``
 
     from django.http import HttpResponseRedirect
     from django.shortcuts import render
@@ -133,7 +133,7 @@ If you want to upload multiple files using one form field, set the ``multiple``
 HTML attribute of field's widget:
 
 .. code-block:: python
-    :caption: forms.py
+    :caption: ``forms.py``
 
     from django import forms
 
@@ -145,7 +145,7 @@ Then override the ``post`` method of your
 uploads:
 
 .. code-block:: python
-    :caption: views.py
+    :caption: ``views.py``
 
     from django.views.generic.edit import FormView
     from .forms import FileFieldForm
diff --git a/docs/topics/http/urls.txt b/docs/topics/http/urls.txt
index 31671db81d6..fc8b0563963 100644
--- a/docs/topics/http/urls.txt
+++ b/docs/topics/http/urls.txt
@@ -771,7 +771,7 @@ so that it takes the instance namespace into consideration when creating and
 displaying polls.
 
 .. code-block:: python
-    :caption: urls.py
+    :caption: ``urls.py``
 
     from django.urls import include, path
 
@@ -781,7 +781,7 @@ displaying polls.
     ]
 
 .. code-block:: python
-    :caption: polls/urls.py
+    :caption: ``polls/urls.py``
 
     from django.urls import path
 
@@ -840,7 +840,7 @@ module, or a string reference to the module, to :func:`~django.urls.include`,
 not the list of ``urlpatterns`` itself.
 
 .. code-block:: python
-    :caption: polls/urls.py
+    :caption: ``polls/urls.py``
 
     from django.urls import path
 
@@ -854,7 +854,7 @@ not the list of ``urlpatterns`` itself.
     ]
 
 .. code-block:: python
-    :caption: urls.py
+    :caption: ``urls.py``
 
     from django.urls import include, path
 
diff --git a/docs/topics/logging.txt b/docs/topics/logging.txt
index 744438472e7..56b6daa25b0 100644
--- a/docs/topics/logging.txt
+++ b/docs/topics/logging.txt
@@ -242,7 +242,7 @@ To begin, here's a small configuration that will allow you to output all log
 messages to the console:
 
 .. code-block:: python
-    :caption: settings.py
+    :caption: ``settings.py``
 
     import os
 
@@ -270,7 +270,7 @@ logging system print more messages from just the :ref:`django-logger` named
 logger:
 
 .. code-block:: python
-    :caption: settings.py
+    :caption: ``settings.py``
 
     import os
 
@@ -307,7 +307,7 @@ You don't have to log to the console. Here's a configuration which writes all
 logging from the :ref:`django-logger` named logger to a local file:
 
 .. code-block:: python
-    :caption: settings.py
+    :caption: ``settings.py``
 
     LOGGING = {
         'version': 1,
@@ -334,7 +334,7 @@ location that's writable by the user that's running the Django application.
 Finally, here's an example of a fairly complex logging setup:
 
 .. code-block:: python
-    :caption: settings.py
+    :caption: ``settings.py``
 
     LOGGING = {
         'version': 1,
@@ -479,7 +479,7 @@ Here's an example that disables Django's logging configuration and then
 manually configures logging:
 
 .. code-block:: python
-    :caption: settings.py
+    :caption: ``settings.py``
 
     LOGGING_CONFIG = None
 
diff --git a/docs/topics/testing/advanced.txt b/docs/topics/testing/advanced.txt
index bc562e7ebca..b9927ae9bba 100644
--- a/docs/topics/testing/advanced.txt
+++ b/docs/topics/testing/advanced.txt
@@ -88,7 +88,7 @@ must ensure that they are configured correctly, by calling
 For example, assuming the following class-based view:
 
 .. code-block:: python
-    :caption: views.py
+    :caption: ``views.py``
 
     from django.views.generic import TemplateView
 
@@ -105,7 +105,7 @@ the view, then passing a ``request`` to ``setup()``, before proceeding with
 your test's code:
 
 .. code-block:: python
-    :caption: tests.py
+    :caption: ``tests.py``
 
     from django.test import RequestFactory, TestCase
     from .views import HomeView
@@ -412,7 +412,7 @@ following structure::
 Let's take a look inside a couple of those files:
 
 .. code-block:: python
-    :caption: runtests.py
+    :caption: ``runtests.py``
 
     #!/usr/bin/env python
     import os
@@ -440,7 +440,7 @@ command-line options for controlling verbosity, passing in specific test
 labels to run, etc.
 
 .. code-block:: python
-    :caption: tests/test_settings.py
+    :caption: ``tests/test_settings.py``
 
     SECRET_KEY = 'fake-key'
     INSTALLED_APPS = [