[2.1.x] Refs #20910 -- Replaced snippet directive with code-block.

Backport of c49ea6f5911296dcb40190c905e38b43cdc7c7a3 from master
author: Curtis Maloney <curtis@tinbrain.net> 2018-09-11 03:00:34 +1000
committer: Tim Graham <timograham@gmail.com> 2018-09-10 14:38:08 -0400
commit: 1853e2dbf2e290ec04e3389d523bbe4bad94a42e (patch)
tree: c63e2721c7e691ae88a4ad9e5135b1f042bab857 /docs/intro
parent: 2b2474b75d63fcded37b872fcd2bb543d7502a8a (diff)
9 files changed, 120 insertions, 120 deletions
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 </topics/db/models>` 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 </ref/contrib/admin/index>` --
 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
 </howto/static-files/index>`, might look like:
 
-.. snippet:: html+django
-    :filename: mysite/templates/base.html
+.. code-block:: html+django
+    :caption: mysite/templates/base.html
 
     {% load static %}
     <html>
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 </intro/tutorial02>`. 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 %}
         <ul>
@@ -211,8 +211,8 @@ Put the following code in that template:
 
 Now let's update our ``index`` view in ``polls/views.py`` to use the template:
 
-.. snippet::
-    :filename: polls/views.py
+.. code-block:: python
+    :caption: polls/views.py
 
     from django.http import HttpResponse
     from django.template import loader
@@ -244,8 +244,8 @@ It's a very common idiom to load a template, fill a context and return an
 template. Django provides a shortcut. Here's the full ``index()`` view,
 rewritten:
 
-.. snippet::
-    :filename: polls/views.py
+.. code-block:: python
+    :caption: polls/views.py
 
     from django.shortcuts import render
 
@@ -273,8 +273,8 @@ Raising a 404 error
 Now, let's tackle the question detail view -- the page that displays the question text
 for a given poll. Here's the view:
 
-.. snippet::
-    :filename: polls/views.py
+.. code-block:: python
+    :caption: polls/views.py
 
     from django.http import Http404
     from django.shortcuts import render
@@ -295,8 +295,8 @@ We'll discuss what you could put in that ``polls/detail.html`` template a bit
 later, but if you'd like to quickly get the above example working, a file
 containing just:
 
-.. snippet:: html+django
-    :filename: polls/templates/polls/detail.html
+.. code-block:: html+django
+    :caption: polls/templates/polls/detail.html
 
     {{ question }}
 
@@ -309,8 +309,8 @@ It's a very common idiom to use :meth:`~django.db.models.query.QuerySet.get`
 and raise :exc:`~django.http.Http404` if the object doesn't exist. Django
 provides a shortcut. Here's the ``detail()`` view, rewritten:
 
-.. snippet::
-    :filename: polls/views.py
+.. code-block:: python
+    :caption: polls/views.py
 
     from django.shortcuts import get_object_or_404, render
 
@@ -351,8 +351,8 @@ Back to the ``detail()`` view for our poll application. Given the context
 variable ``question``, here's what the ``polls/detail.html`` template might look
 like:
 
-.. snippet:: html+django
-    :filename: polls/templates/polls/detail.html
+.. code-block:: html+django
+    :caption: polls/templates/polls/detail.html
 
     <h1>{{ question.question_text }}</h1>
     <ul>
@@ -425,8 +425,8 @@ make it so that Django knows which app view to create for a url when using the
 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:
 
-.. snippet::
-    :filename: polls/urls.py
+.. code-block:: python
+    :caption: polls/urls.py
 
     from django.urls import path
 
@@ -442,15 +442,15 @@ file, go ahead and add an ``app_name`` to set the application namespace:
 
 Now change your ``polls/index.html`` template from:
 
-.. snippet:: html+django
-    :filename: polls/templates/polls/index.html
+.. code-block:: html+django
+    :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:
 
-.. snippet:: html+django
-    :filename: polls/templates/polls/index.html
+.. code-block:: html+django
+    :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 65caef3043..2eacd297ed 100644
--- a/docs/intro/tutorial04.txt
+++ b/docs/intro/tutorial04.txt
@@ -12,8 +12,8 @@ Write a simple form
 Let's update our poll detail template ("polls/detail.html") from the last
 tutorial, so that the template contains an HTML ``<form>`` element:
 
-.. snippet:: html+django
-    :filename: polls/templates/polls/detail.html
+.. code-block:: html+django
+    :caption: polls/templates/polls/detail.html
 
     <h1>{{ question.question_text }}</h1>
 
@@ -58,16 +58,16 @@ Now, let's create a Django view that handles the submitted data and does
 something with it. Remember, in :doc:`Tutorial 3 </intro/tutorial03>`, we
 created a URLconf for the polls application that includes this line:
 
-.. snippet::
-    :filename: polls/urls.py
+.. code-block:: python
+    :caption: polls/urls.py
 
     path('<int:question_id>/vote/', views.vote, name='vote'),
 
 We also created a dummy implementation of the ``vote()`` function. Let's
 create a real version. Add the following to ``polls/views.py``:
 
-.. snippet::
-    :filename: polls/views.py
+.. code-block:: python
+    :caption: polls/views.py
 
     from django.http import HttpResponse, HttpResponseRedirect
     from django.shortcuts import get_object_or_404, render
@@ -146,8 +146,8 @@ response documentation </ref/request-response>`.
 After somebody votes in a question, the ``vote()`` view redirects to the results
 page for the question. Let's write that view:
 
-.. snippet::
-    :filename: polls/views.py
+.. code-block:: python
+    :caption: polls/views.py
 
     from django.shortcuts import get_object_or_404, render
 
@@ -162,8 +162,8 @@ redundancy later.
 
 Now, create a ``polls/results.html`` template:
 
-.. snippet:: html+django
-    :filename: polls/templates/polls/results.html
+.. code-block:: html+django
+    :caption: polls/templates/polls/results.html
 
     <h1>{{ question.question_text }}</h1>
 
@@ -234,8 +234,8 @@ Amend URLconf
 
 First, open the ``polls/urls.py`` URLconf and change it like so:
 
-.. snippet::
-    :filename: polls/urls.py
+.. code-block:: python
+    :caption: polls/urls.py
 
     from django.urls import path
 
@@ -259,8 +259,8 @@ Next, we're going to remove our old ``index``, ``detail``, and ``results``
 views and use Django's generic views instead. To do so, open the
 ``polls/views.py`` file and change it like so:
 
-.. snippet::
-    :filename: polls/views.py
+.. code-block:: python
+    :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 c6c5e2900d..42891a6ecd 100644
--- a/docs/intro/tutorial05.txt
+++ b/docs/intro/tutorial05.txt
@@ -166,8 +166,8 @@ whose name begins with ``test``.
 
 Put the following in the ``tests.py`` file in the ``polls`` application:
 
-.. snippet::
-    :filename: polls/tests.py
+.. code-block:: python
+    :caption: polls/tests.py
 
     import datetime
 
@@ -248,8 +248,8 @@ return ``False`` if its ``pub_date`` is in the future. Amend the method in
 ``models.py``, so that it will only return ``True`` if the date is also in the
 past:
 
-.. snippet::
-    :filename: polls/models.py
+.. code-block:: python
+    :caption: polls/models.py
 
     def was_published_recently(self):
         now = timezone.now()
@@ -284,8 +284,8 @@ introduced another.
 Add two more test methods to the same class, to test the behavior of the method
 more comprehensively:
 
-.. snippet::
-    :filename: polls/tests.py
+.. code-block:: python
+    :caption: polls/tests.py
 
     def test_was_published_recently_with_old_question(self):
         """
@@ -400,8 +400,8 @@ The list of polls shows polls that aren't published yet (i.e. those that have a
 In :doc:`Tutorial 4 </intro/tutorial04>` we introduced a class-based view,
 based on :class:`~django.views.generic.list.ListView`:
 
-.. snippet::
-    :filename: polls/views.py
+.. code-block:: python
+    :caption: polls/views.py
 
     class IndexView(generic.ListView):
         template_name = 'polls/index.html'
@@ -415,15 +415,15 @@ We need to amend the ``get_queryset()`` method and change it so that it also
 checks the date by comparing it with ``timezone.now()``. First we need to add
 an import:
 
-.. snippet::
-    :filename: polls/views.py
+.. code-block:: python
+    :caption: polls/views.py
 
     from django.utils import timezone
 
 and then we must amend the ``get_queryset`` method like so:
 
-.. snippet::
-    :filename: polls/views.py
+.. code-block:: python
+    :caption: polls/views.py
 
     def get_queryset(self):
         """
@@ -450,16 +450,16 @@ our :djadmin:`shell` session above.
 
 Add the following to ``polls/tests.py``:
 
-.. snippet::
-    :filename: polls/tests.py
+.. code-block:: python
+    :caption: polls/tests.py
 
     from django.urls import reverse
 
 and we'll create a shortcut function to create questions as well as a new test
 class:
 
-.. snippet::
-    :filename: polls/tests.py
+.. code-block:: python
+    :caption: polls/tests.py
 
     def create_question(question_text, days):
         """
@@ -559,8 +559,8 @@ What we have works well; however, even though future questions don't appear in
 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``:
 
-.. snippet::
-    :filename: polls/views.py
+.. code-block:: python
+    :caption: polls/views.py
 
     class DetailView(generic.DetailView):
         ...
@@ -574,8 +574,8 @@ And of course, we will add some tests, to check that a ``Question`` whose
 ``pub_date`` is in the past can be displayed, and that one with a ``pub_date``
 in the future is not:
 
-.. snippet::
-    :filename: polls/tests.py
+.. code-block:: python
+    :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 dff3bc1e2c..db1f1f47fd 100644
--- a/docs/intro/tutorial06.txt
+++ b/docs/intro/tutorial06.txt
@@ -56,8 +56,8 @@ reference the path for templates.
 
 Put the following code in that stylesheet (``polls/static/polls/style.css``):
 
-.. snippet:: css
-    :filename: polls/static/polls/style.css
+.. code-block:: css
+    :caption: polls/static/polls/style.css
 
     li a {
         color: green;
@@ -65,8 +65,8 @@ 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``:
 
-.. snippet:: html+django
-    :filename: polls/templates/polls/index.html
+.. code-block:: html+django
+    :caption: polls/templates/polls/index.html
 
     {% load static %}
 
@@ -88,8 +88,8 @@ called ``background.gif``. In other words, put your image in
 
 Then, add to your stylesheet (``polls/static/polls/style.css``):
 
-.. snippet:: css
-    :filename: polls/static/polls/style.css
+.. code-block:: 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 5924f55c6a..001c6ec998 100644
--- a/docs/intro/tutorial07.txt
+++ b/docs/intro/tutorial07.txt
@@ -18,8 +18,8 @@ Django the options you want when you register the object.
 Let's see how this works by reordering the fields on the edit form. Replace
 the ``admin.site.register(Question)`` line with:
 
-.. snippet::
-    :filename: polls/admin.py
+.. code-block:: python
+    :caption: polls/admin.py
 
     from django.contrib import admin
 
@@ -47,8 +47,8 @@ of fields, choosing an intuitive order is an important usability detail.
 And speaking of forms with dozens of fields, you might want to split the form
 up into fieldsets:
 
-.. snippet::
-    :filename: polls/admin.py
+.. code-block:: python
+    :caption: polls/admin.py
 
     from django.contrib import admin
 
@@ -81,8 +81,8 @@ Yet.
 There are two ways to solve this problem. The first is to register ``Choice``
 with the admin just as we did with ``Question``. That's easy:
 
-.. snippet::
-    :filename: polls/admin.py
+.. code-block:: python
+    :caption: polls/admin.py
 
     from django.contrib import admin
 
@@ -115,8 +115,8 @@ It'd be better if you could add a bunch of Choices directly when you create the
 Remove the ``register()`` call for the ``Choice`` model. Then, edit the ``Question``
 registration code to read:
 
-.. snippet::
-    :filename: polls/admin.py
+.. code-block:: python
+    :caption: polls/admin.py
 
     from django.contrib import admin
 
@@ -162,8 +162,8 @@ fields for entering related ``Choice`` objects. For that reason, Django offers a
 tabular way of displaying inline related objects; you just need to change
 the ``ChoiceInline`` declaration to read:
 
-.. snippet::
-    :filename: polls/admin.py
+.. code-block:: python
+    :caption: polls/admin.py
 
     class ChoiceInline(admin.TabularInline):
         #...
@@ -194,8 +194,8 @@ more helpful if we could display individual fields. To do that, use the
 tuple of field names to display, as columns, on the change list page for the
 object:
 
-.. snippet::
-    :filename: polls/admin.py
+.. code-block:: python
+    :caption: polls/admin.py
 
     class QuestionAdmin(admin.ModelAdmin):
         # ...
@@ -204,8 +204,8 @@ object:
 Just for good measure, let's also include the ``was_published_recently()``
 method from :doc:`Tutorial 2 </intro/tutorial02>`:
 
-.. snippet::
-    :filename: polls/admin.py
+.. code-block:: python
+    :caption: polls/admin.py
 
     class QuestionAdmin(admin.ModelAdmin):
         # ...
@@ -226,8 +226,8 @@ representation of the output.
 You can improve that by giving that method (in :file:`polls/models.py`) a few
 attributes, as follows:
 
-.. snippet::
-    :filename: polls/models.py
+.. code-block:: python
+    :caption: polls/models.py
 
     class Question(models.Model):
         # ...
@@ -301,8 +301,8 @@ keeping your templates within the project is a good convention to follow.
 Open your settings file (:file:`mysite/settings.py`, remember) and add a
 :setting:`DIRS <TEMPLATES-DIRS>` option in the :setting:`TEMPLATES` setting:
 
-.. snippet::
-    :filename: mysite/settings.py
+.. code-block:: python
+    :caption: mysite/settings.py
 
     TEMPLATES = [
         {
author	Curtis Maloney <curtis@tinbrain.net>	2018-09-11 03:00:34 +1000
committer	Tim Graham <timograham@gmail.com>	2018-09-10 14:38:08 -0400
commit	1853e2dbf2e290ec04e3389d523bbe4bad94a42e (patch)
tree	c63e2721c7e691ae88a4ad9e5135b1f042bab857 /docs/intro
parent	2b2474b75d63fcded37b872fcd2bb543d7502a8a (diff)