Prevented (and corrected) single backtick usage in docs.

docs/_ext/djangodocs.py

@@ -11,10 +11,11 @@
 from sphinx import addnodes
 from sphinx.builders.html import StandaloneHTMLBuilder
 from sphinx.directives import CodeBlock
+from sphinx.errors import SphinxError
 from sphinx.domains.std import Cmdoption
 from sphinx.errors import ExtensionError
 from sphinx.util import logging
-from sphinx.util.console import bold
+from sphinx.util.console import bold, red
 from sphinx.writers.html import HTMLTranslator
 
 logger = logging.getLogger(__name__)
@@ -67,6 +68,7 @@ def setup(app):
     )
     app.add_directive('console', ConsoleDirective)
     app.connect('html-page-context', html_page_context_hook)
+    app.add_role('default-role-error', default_role_error)
     return {'parallel_read_safe': True}
 
 
@@ -371,3 +373,14 @@ def html_page_context_hook(app, pagename, templatename, context, doctree):
     # 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)
+
+
+def default_role_error(
+    name, rawtext, text, lineno, inliner, options=None, content=None
+):
+    msg = (
+        "Default role used (`single backticks`) at line %s: %s. Did you mean "
+        "to use two backticks for ``code``, or miss an underscore for a "
+        "`link`_ ?" % (lineno, rawtext)
+    )
+    raise SphinxError(red(msg))

docs/conf.py

@@ -127,7 +127,7 @@ def django_release():
 exclude_patterns = ['_build', '_theme']
 
 # The reST default role (used for this markup: `text`) to use for all documents.
-# default_role = None
+default_role = "default-role-error"
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
 add_function_parentheses = True

docs/faq/help.txt

@@ -36,7 +36,7 @@ your choice of words.
 
 .. _message-does-not-appear-on-django-users:
 
-Why hasn't my message appeared on `django-users`?
+Why hasn't my message appeared on *django-users*?
 =================================================
 
 |django-users| has a lot of subscribers. This is good for the community, as

docs/faq/troubleshooting.txt

@@ -10,7 +10,7 @@ during the development of Django applications.
 Problems running ``django-admin``
 =================================
 
-"command not found: `django-admin`"
+``command not found: django-admin``
 -----------------------------------
 
 :doc:`django-admin </ref/django-admin>` should be on your system path if you

docs/howto/deployment/wsgi/uwsgi.txt

@@ -38,7 +38,7 @@ uWSGI model
 -----------
 
 uWSGI operates on a client-server model. Your Web server (e.g., nginx, Apache)
-communicates with a `django-uwsgi` "worker" process to serve dynamic content.
+communicates with a ``django-uwsgi`` "worker" process to serve dynamic content.
 
 Configuring and starting the uWSGI server for Django
 ----------------------------------------------------

docs/howto/error-reporting.txt

@@ -166,8 +166,8 @@ filtered out of error reports in a production environment (that is, where
             ...
 
     In the above example, the values for the ``user``, ``pw`` and ``cc``
-    variables will be hidden and replaced with stars (`**********`) in the
-    error reports, whereas the value of the ``name`` variable will be
+    variables will be hidden and replaced with stars (``**********``)
+    in the error reports, whereas the value of the ``name`` variable will be
     disclosed.
 
     To systematically hide all local variables of a function from error logs,
@@ -213,8 +213,9 @@ filtered out of error reports in a production environment (that is, where
 
     In the above example, the values for the ``pass_word`` and
     ``credit_card_number`` POST parameters will be hidden and replaced with
-    stars (`**********`) in the request's representation inside the error
-    reports, whereas the value of the ``name`` parameter will be disclosed.
+    stars (``**********``) in the request's representation inside the
+    error reports, whereas the value of the ``name`` parameter will be
+    disclosed.
 
     To systematically hide all POST parameters of a request in error reports,
     do not provide any argument to the ``sensitive_post_parameters`` decorator::
@@ -242,9 +243,9 @@ of reports when an error occurs. The actual filtering is done by Django's
 default error reporter filter:
 :class:`django.views.debug.SafeExceptionReporterFilter`. This filter uses the
 decorators' annotations to replace the corresponding values with stars
-(`**********`) when the error reports are produced. If you wish to override or
-customize this default behavior for your entire site, you need to define your
-own filter class and tell Django to use it via the
+(``**********``) when the error reports are produced. If you wish to
+override or customize this default behavior for your entire site, you need to
+define your own filter class and tell Django to use it via the
 :setting:`DEFAULT_EXCEPTION_REPORTER_FILTER` setting::
 
     DEFAULT_EXCEPTION_REPORTER_FILTER = 'path.to.your.CustomExceptionReporterFilter'
@@ -271,7 +272,8 @@ following attributes and methods:
         .. versionadded:: 3.1
 
         The string value to replace sensitive value with. By default it
-        replaces the values of sensitive variables with stars (`**********`).
+        replaces the values of sensitive variables with stars
+        (``**********``).
 
     .. attribute:: hidden_settings
 

docs/howto/outputting-pdf.txt

@@ -75,8 +75,8 @@ mention:
 
 * The response will automatically set the MIME type :mimetype:`application/pdf`
   based on the filename extension. This tells browsers that the document is a
-  PDF file, rather than an HTML file or a generic `application/octet-stream`
-  binary content.
+  PDF file, rather than an HTML file or a generic
+  :mimetype:`application/octet-stream` binary content.
 
 * When ``as_attachment=True`` is passed to ``FileResponse``, it sets the
   appropriate ``Content-Disposition`` header and that tells Web browsers to

docs/internals/contributing/new-contributors.txt

@@ -146,7 +146,7 @@ FAQ
    (except the Django fellow), and sometimes folks just don't have time. The
    best thing to do is to send a gentle reminder to the |django-developers|
    mailing list asking for review on the ticket, or to bring it up in the
-   `#django-dev` IRC channel.
+   ``#django-dev`` IRC channel.
 
 2. **I'm sure my ticket is absolutely 100% perfect, can I mark it as RFC
    myself?**

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

@@ -131,8 +131,8 @@ Testing from the command line
 
 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:
+After installing ``Node.js``, install the JavaScript test dependencies by
+running the following from the root of your Django checkout:
 
 .. console::
 

docs/internals/contributing/writing-code/unit-tests.txt

@@ -124,7 +124,7 @@ Running the JavaScript tests
 
 Django includes a set of :ref:`JavaScript unit tests <javascript-tests>` for
 functions in certain contrib apps. The JavaScript tests aren't run by default
-using ``tox`` because they require `Node.js` to be installed and aren't
+using ``tox`` because they require ``Node.js`` to be installed and aren't
 necessary for the majority of patches. To run the JavaScript tests using
 ``tox``:
 

docs/internals/howto-release-django.txt

@@ -379,7 +379,7 @@ Now you're ready to actually put the release out there. To do this:
    message body should include the vulnerability details, for example, the
    announcement blog post text. Include a link to the announcement blog post.
 
-#. Add a link to the blog post in the topic of the `#django` IRC channel:
+#. Add a link to the blog post in the topic of the ``#django`` IRC channel:
    ``/msg chanserv TOPIC #django new topic goes here``.
 
 Post-release

docs/ref/contrib/gis/geoip2.txt

@@ -9,8 +9,8 @@ The :class:`GeoIP2` object is a wrapper for the `MaxMind geoip2 Python
 library`__. [#]_
 
 In order to perform IP-based geolocation, the :class:`GeoIP2` object requires
-the `geoip2 Python library`__ and the GeoIP `Country` and/or `City` `datasets
-in binary format`__ (the CSV files will not work!). Grab the
+the `geoip2 Python library`__ and the GeoIP ``Country`` and/or ``City``
+`datasets in binary format`__ (the CSV files will not work!). Grab the
 ``GeoLite2-Country.mmdb.gz`` and ``GeoLite2-City.mmdb.gz`` files and unzip them
 in a directory corresponding to the :setting:`GEOIP_PATH` setting.
 

docs/ref/contrib/gis/geoquerysets.txt

@@ -743,9 +743,9 @@ Distance lookups take the following form::
 The value passed into a distance lookup is a tuple; the first two
 values are mandatory, and are the geometry to calculate distances to,
 and a distance value (either a number in units of the field, a
-:class:`~django.contrib.gis.measure.Distance` object, or a `query expression
-<ref/models/expressions>`). To pass a band index to the lookup, use a 3-tuple
-where the second entry is the band index.
+:class:`~django.contrib.gis.measure.Distance` object, or a :doc:`query
+expression </ref/models/expressions>`). To pass a band index to the lookup, use
+a 3-tuple where the second entry is the band index.
 
 On every distance lookup except :lookup:`dwithin`, an optional element,
 ``'spheroid'``, may be included to use the more accurate spheroid distance

docs/ref/csrf.txt

@@ -531,7 +531,7 @@ Is it a problem that Django's CSRF protection isn't linked to a session by defau
 -----------------------------------------------------------------------------------
 
 No, this is by design. Not linking CSRF protection to a session allows using
-the protection on sites such as a `pastebin` that allow submissions from
+the protection on sites such as a *pastebin* that allow submissions from
 anonymous users which don't have a session.
 
 If you wish to store the CSRF token in the user's session, use the

docs/ref/forms/widgets.txt

@@ -365,7 +365,7 @@ foundation for custom widgets.
         the ``name`` attribute on each subwidget. In this case, for each
         ``(key, widget)`` pair, the key will be appended to the ``name`` of the
         widget in order to generate the attribute value. You may provide the
-        empty string (`''`) for a single key, in order to suppress the suffix
+        empty string (``''``) for a single key, in order to suppress the suffix
         for one widget. For example::
 
             >>> widget = MultiWidget(widgets={'': TextInput, 'last': TextInput})

docs/ref/models/fields.txt

@@ -153,7 +153,7 @@ The first element in each tuple is the name to apply to the group. The
 second element is an iterable of 2-tuples, with each 2-tuple containing
 a value and a human-readable name for an option. Grouped options may be
 combined with ungrouped options within a single list (such as the
-`unknown` option in this example).
+``'unknown'`` option in this example).
 
 For each model field that has :attr:`~Field.choices` set, Django will add a
 method to retrieve the human-readable name for the field's current value. See

docs/ref/request-response.txt

@@ -798,7 +798,8 @@ Methods
     ``content_type`` is the MIME type optionally completed by a character set
     encoding and is used to fill the HTTP ``Content-Type`` header. If not
     specified, it is formed by ``'text/html'`` and the
-    :setting:`DEFAULT_CHARSET` settings, by default: "`text/html; charset=utf-8`".
+    :setting:`DEFAULT_CHARSET` settings, by default:
+    ``"text/html; charset=utf-8"``.
 
     ``status`` is the :rfc:`HTTP status code <7231#section-6>` for the response.
     You can use Python's :py:class:`http.HTTPStatus` for meaningful aliases,

docs/releases/0.95.txt

@@ -109,7 +109,7 @@ many common questions appear with some regularity, and any particular problem
 may already have been answered.
 
 Finally, for those who prefer the more immediate feedback offered by IRC,
-there's a `#django` channel on irc.freenode.net that is regularly populated
+there's a ``#django`` channel on irc.freenode.net that is regularly populated
 by Django users and developers from around the world. Friendly people are
 usually available at any hour of the day -- to help, or just to chat.
 

docs/releases/1.11.1.txt

@@ -10,7 +10,7 @@ Allowed disabling server-side cursors on PostgreSQL
 ===================================================
 
 The change in Django 1.11 to make :meth:`.QuerySet.iterator()` use server-side
-cursors on PostgreSQL prevents running Django with `pgBouncer` in transaction
+cursors on PostgreSQL prevents running Django with pgBouncer in transaction
 pooling mode. To reallow that, use the :setting:`DISABLE_SERVER_SIDE_CURSORS
 <DATABASE-DISABLE_SERVER_SIDE_CURSORS>` setting in :setting:`DATABASES`.
 

docs/releases/1.11.txt

@@ -185,8 +185,8 @@ Minor features
 
 * PostGIS migrations can now change field dimensions.
 
-* Added the ability to pass the `size`, `shape`, and `offset` parameter when
-  creating :class:`~django.contrib.gis.gdal.GDALRaster` objects.
+* Added the ability to pass the ``size``, ``shape``, and ``offset`` parameters
+  when creating :class:`~django.contrib.gis.gdal.GDALRaster` objects.
 
 * Added SpatiaLite support for the
   :class:`~django.contrib.gis.db.models.functions.IsValid` function,
@@ -644,8 +644,8 @@ Server-side cursors on PostgreSQL
 ---------------------------------
 
 The change to make :meth:`.QuerySet.iterator()` use server-side cursors on
-PostgreSQL prevents running Django with `pgBouncer` in transaction pooling
-mode. To reallow that, use the :setting:`DISABLE_SERVER_SIDE_CURSORS
+PostgreSQL prevents running Django with pgBouncer in transaction pooling mode.
+To reallow that, use the :setting:`DISABLE_SERVER_SIDE_CURSORS
 <DATABASE-DISABLE_SERVER_SIDE_CURSORS>` setting (added in Django 1.11.1) in
 :setting:`DATABASES`.
 

docs/releases/1.2.txt

@@ -811,16 +811,16 @@ This affects the following settings:
 =========================================  ==========================
  Old setting                                New Setting
 =========================================  ==========================
-`DATABASE_ENGINE`                          :setting:`ENGINE <DATABASE-ENGINE>`
-`DATABASE_HOST`                            :setting:`HOST`
-`DATABASE_NAME`                            :setting:`NAME`
-`DATABASE_OPTIONS`                         :setting:`OPTIONS`
-`DATABASE_PASSWORD`                        :setting:`PASSWORD`
-`DATABASE_PORT`                            :setting:`PORT`
-`DATABASE_USER`                            :setting:`USER`
-`TEST_DATABASE_CHARSET`                    :setting:`TEST_CHARSET`
-`TEST_DATABASE_COLLATION`                  :setting:`TEST_COLLATION`
-`TEST_DATABASE_NAME`                       :setting:`TEST_NAME`
+``DATABASE_ENGINE``                        :setting:`ENGINE <DATABASE-ENGINE>`
+``DATABASE_HOST``                          :setting:`HOST`
+``DATABASE_NAME``                          :setting:`NAME`
+``DATABASE_OPTIONS``                       :setting:`OPTIONS`
+``DATABASE_PASSWORD``                      :setting:`PASSWORD`
+``DATABASE_PORT``                          :setting:`PORT`
+``DATABASE_USER``                          :setting:`USER`
+``TEST_DATABASE_CHARSET``                  :setting:`TEST_CHARSET`
+``TEST_DATABASE_COLLATION``                :setting:`TEST_COLLATION`
+``TEST_DATABASE_NAME``                     :setting:`TEST_NAME`
 =========================================  ==========================
 
 These changes are also required if you have manually created a database

docs/releases/1.4.13.txt

@@ -40,8 +40,8 @@ Django relies on user input in some cases (e.g.
 :doc:`i18n </topics/i18n/index>`) to redirect the user to an "on success" URL.
 The security checks for these redirects (namely
 ``django.utils.http.is_safe_url()``) did not correctly validate some malformed
-URLs, such as `http:\\\\\\djangoproject.com`, which are accepted by some browsers
-with more liberal URL parsing.
+URLs, such as ``http:\\\\\\djangoproject.com``, which are accepted by some
+browsers with more liberal URL parsing.
 
 To remedy this, the validation in ``is_safe_url()`` has been tightened to be able
 to handle and correctly validate these malformed URLs.

docs/releases/1.4.18.txt

@@ -12,7 +12,7 @@ WSGI header spoofing via underscore/dash conflation
 
 When HTTP headers are placed into the WSGI environ, they are normalized by
 converting to uppercase, converting all dashes to underscores, and prepending
-`HTTP_`. For instance, a header ``X-Auth-User`` would become
+``HTTP_``. For instance, a header ``X-Auth-User`` would become
 ``HTTP_X_AUTH_USER`` in the WSGI environ (and thus also in Django's
 ``request.META`` dictionary).
 

docs/releases/1.4.txt

@@ -634,9 +634,9 @@ Django 1.4 also includes several smaller improvements worth noting:
   :meth:`~django.db.models.query.QuerySet.distinct`.
 
 * The admin login page will add a password reset link if you include a URL with
-  the name `'admin_password_reset'` in your urls.py, so plugging in the built-in
-  password reset mechanism and making it available is now much easier. For
-  details, see :ref:`auth_password_reset`.
+  the name ``'admin_password_reset'`` in your urls.py, so plugging in the
+  built-in password reset mechanism and making it available is now much easier.
+  For details, see :ref:`auth_password_reset`.
 
 * The MySQL database backend can now make use of the savepoint feature
   implemented by MySQL version 5.0.3 or newer with the InnoDB storage engine.
@@ -671,9 +671,9 @@ vulnerabilities. No Django site should ever be run without a
 :setting:`SECRET_KEY`.
 
 In Django 1.4, starting Django with an empty :setting:`SECRET_KEY` will raise a
-`DeprecationWarning`. In Django 1.5, it will raise an exception and Django will
-refuse to start. This is slightly accelerated from the usual deprecation path
-due to the severity of the consequences of running Django with no
+``DeprecationWarning``. In Django 1.5, it will raise an exception and Django
+will refuse to start. This is slightly accelerated from the usual deprecation
+path due to the severity of the consequences of running Django with no
 :setting:`SECRET_KEY`.
 
 ``django.contrib.admin``
@@ -909,8 +909,8 @@ doesn't make any effort to synchronize access to the underlying backend.
 Concurrency behavior is defined by the underlying backend implementation.
 Check their documentation for details.
 
-`COMMENTS_BANNED_USERS_GROUP` setting
--------------------------------------
+``COMMENTS_BANNED_USERS_GROUP`` setting
+---------------------------------------
 
 Django's comments has historically
 supported excluding the comments of a special user group, but we've never
@@ -946,8 +946,8 @@ Save this model manager in your custom comment app (e.g., in
 
         objects = BanningCommentManager()
 
-`IGNORABLE_404_STARTS` and `IGNORABLE_404_ENDS` settings
---------------------------------------------------------
+``IGNORABLE_404_STARTS`` and ``IGNORABLE_404_ENDS`` settings
+------------------------------------------------------------
 
 Until Django 1.3, it was possible to exclude some URLs from Django's
 :doc:`404 error reporting</howto/error-reporting>` by adding prefixes to
@@ -1294,8 +1294,8 @@ Now, the flags are keyword arguments of :meth:`@register.filter
 
 See :ref:`filters and auto-escaping <filters-auto-escaping>` for more information.
 
-Wildcard expansion of application names in `INSTALLED_APPS`
------------------------------------------------------------
+Wildcard expansion of application names in ``INSTALLED_APPS``
+-------------------------------------------------------------
 
 Until Django 1.3, :setting:`INSTALLED_APPS` accepted wildcards in application
 names, like ``django.contrib.*``. The expansion was performed by a

docs/releases/1.5.8.txt

@@ -40,8 +40,8 @@ Django relies on user input in some cases (e.g.
 :doc:`i18n </topics/i18n/index>`) to redirect the user to an "on success" URL.
 The security checks for these redirects (namely
 ``django.utils.http.is_safe_url()``) did not correctly validate some malformed
-URLs, such as `http:\\\\\\djangoproject.com`, which are accepted by some browsers
-with more liberal URL parsing.
+URLs, such as ``http:\\\\\\djangoproject.com``, which are accepted by some
+browsers with more liberal URL parsing.
 
 To remedy this, the validation in ``is_safe_url()`` has been tightened to be able
 to handle and correctly validate these malformed URLs.

docs/releases/1.5.txt

@@ -615,8 +615,8 @@ database state behind or unit tests that rely on some form of state being
 preserved after the execution of other tests. Such tests are already very
 fragile, and must now be changed to be able to run independently.
 
-`cleaned_data` dictionary kept for invalid forms
-------------------------------------------------
+``cleaned_data`` dictionary kept for invalid forms
+--------------------------------------------------
 
 The :attr:`~django.forms.Form.cleaned_data` dictionary is now always present
 after form validation. When the form doesn't validate, it contains only the