diff --git a/docs/conf.py b/docs/conf.py index 4306abd6dd..11d637cb5c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -43,12 +43,6 @@ extensions = [ "sphinx.ext.viewcode", ] -extlinks = { - 'commit': ('https://github.com/django/django/commit/%s', ''), - 'cve': ('https://nvd.nist.gov/view/vuln/detail?vulnId=%s', 'CVE-'), - 'ticket': ('https://code.djangoproject.com/ticket/%s', '#'), -} - # Spelling check needs an additional module that is not installed by default. # Add it only if spelling check is requested so docs can be generated without it. if 'spelling' in sys.argv: @@ -100,6 +94,14 @@ else: # The "development version" of Django django_next_version = '3.0' +extlinks = { + 'commit': ('https://github.com/django/django/commit/%s', ''), + 'cve': ('https://nvd.nist.gov/view/vuln/detail?vulnId=%s', 'CVE-'), + # A file or directory. GitHub redirects from blob to tree if needed. + 'source': ('https://github.com/django/django/blob/stable/' + version + '.x/%s', ''), + 'ticket': ('https://code.djangoproject.com/ticket/%s', '#'), +} + # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. # language = None diff --git a/docs/faq/general.txt b/docs/faq/general.txt index 2d01d337f1..9dc4d1b0d4 100644 --- a/docs/faq/general.txt +++ b/docs/faq/general.txt @@ -74,17 +74,16 @@ newspaper in Lawrence, Kansas, USA. Django's now run by an international How is Django licensed? ======================= -Django is distributed under `the 3-clause BSD license -`_. This is an open -source license granting broad permissions to modify and redistribute Django. +Django is distributed under :source:`the 3-clause BSD license `. This +is an open source license granting broad permissions to modify and redistribute +Django. Why does Django include Python's license file? ============================================== Django includes code from the Python standard library. Python is distributed -under a permissive open source license. `A copy of the Python license -`_ is -included with Django for compliance with Python's terms. +under a permissive open source license. :source:`A copy of the Python license +` is included with Django for compliance with Python's terms. Which sites use Django? ======================= @@ -183,15 +182,13 @@ The Django docs are available in the ``docs`` directory of each Django tarball release. These docs are in reST (reStructuredText) format, and each text file corresponds to a Web page on the official Django site. -Because the documentation is `stored in revision control`_, you can browse -documentation changes just like you can browse code changes. +Because the documentation is :source:`stored in revision control `, you +can browse documentation changes just like you can browse code changes. Technically, the docs on Django's site are generated from the latest development versions of those reST documents, so the docs on the Django site may offer more information than the docs that come with the latest Django release. -.. _stored in revision control: https://github.com/django/django/tree/master/docs/ - How do I cite Django? ===================== diff --git a/docs/intro/whatsnext.txt b/docs/intro/whatsnext.txt index 499376d1a3..718be49669 100644 --- a/docs/intro/whatsnext.txt +++ b/docs/intro/whatsnext.txt @@ -97,10 +97,8 @@ reasons: Django APIs or behaviors change. Django's documentation is kept in the same source control system as its code. It -lives in the `docs`_ directory of our Git repository. Each document online is a -separate text file in the repository. - -.. _docs: https://github.com/django/django/tree/master/docs +lives in the :source:`docs` directory of our Git repository. Each document +online is a separate text file in the repository. Where to get it =============== diff --git a/docs/ref/contrib/flatpages.txt b/docs/ref/contrib/flatpages.txt index dfffb61ec6..f9126cc9e2 100644 --- a/docs/ref/contrib/flatpages.txt +++ b/docs/ref/contrib/flatpages.txt @@ -213,11 +213,9 @@ Via the Python API Flatpages are represented by a standard :doc:`Django model `, - which lives in `django/contrib/flatpages/models.py`_. You can access + which lives in :source:`django/contrib/flatpages/models.py`. You can access flatpage objects via the :doc:`Django database API `. -.. _django/contrib/flatpages/models.py: https://github.com/django/django/blob/master/django/contrib/flatpages/models.py - .. currentmodule:: django.contrib.flatpages .. admonition:: Check for duplicate flatpage URLs. diff --git a/docs/ref/contrib/gis/db-api.txt b/docs/ref/contrib/gis/db-api.txt index b70ae11067..d5ddb2564c 100644 --- a/docs/ref/contrib/gis/db-api.txt +++ b/docs/ref/contrib/gis/db-api.txt @@ -268,8 +268,8 @@ to be in the units of the field. in your field definition. For example, let's say we have a ``SouthTexasCity`` model (from the -`GeoDjango distance tests`__ ) on a *projected* coordinate system valid for cities -in southern Texas:: +:source:`GeoDjango distance tests ` ) on a +*projected* coordinate system valid for cities in southern Texas:: from django.contrib.gis.db import models @@ -303,8 +303,6 @@ both. To specify the band index of a raster input on the right hand side, a Where the band with index 2 (the third band) of the raster ``rst`` would be used for the lookup. -__ https://github.com/django/django/blob/master/tests/gis_tests/distapp/models.py - .. _compatibility-table: Compatibility Tables diff --git a/docs/ref/contrib/redirects.txt b/docs/ref/contrib/redirects.txt index 15417d6f30..a37aee8711 100644 --- a/docs/ref/contrib/redirects.txt +++ b/docs/ref/contrib/redirects.txt @@ -72,10 +72,8 @@ Via the Python API .. class:: models.Redirect Redirects are represented by a standard :doc:`Django model `, - which lives in `django/contrib/redirects/models.py`_. You can access redirect - objects via the :doc:`Django database API `. - -.. _django/contrib/redirects/models.py: https://github.com/django/django/blob/master/django/contrib/redirects/models.py + which lives in :source:`django/contrib/redirects/models.py`. You can access + redirect objects via the :doc:`Django database API `. Middleware ========== diff --git a/docs/ref/contrib/syndication.txt b/docs/ref/contrib/syndication.txt index ab3fcba5d4..d79db5a94a 100644 --- a/docs/ref/contrib/syndication.txt +++ b/docs/ref/contrib/syndication.txt @@ -892,7 +892,7 @@ The low-level framework Behind the scenes, the high-level RSS framework uses a lower-level framework for generating feeds' XML. This framework lives in a single module: -`django/utils/feedgenerator.py`_. +:source:`django/utils/feedgenerator.py`. You use this framework on your own, for lower-level feed generation. You can also create custom feed generator subclasses for use with the ``feed_type`` @@ -1006,8 +1006,6 @@ For example, to create an Atom 1.0 feed and print it to standard output:: ... -.. _django/utils/feedgenerator.py: https://github.com/django/django/blob/master/django/utils/feedgenerator.py - .. currentmodule:: django.contrib.syndication Custom feed generators diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt index 152108cb82..582eabdd3b 100644 --- a/docs/ref/django-admin.txt +++ b/docs/ref/django-admin.txt @@ -1185,10 +1185,9 @@ Generate squashed migration file without Django version and timestamp header. Creates a Django app directory structure for the given app name in the current directory or the given destination. -By default the directory created contains a ``models.py`` file and other app -template files. (See the `source`_ for more details.) If only the app -name is given, the app directory will be created in the current working -directory. +By default, :source:`the new directory ` contains a +``models.py`` file and other app template files. If only the app name is given, +the app directory will be created in the current working directory. If the optional destination is provided, Django will use that existing directory rather than creating a new one. You can use '.' to denote the current @@ -1260,8 +1259,6 @@ files is: byte-compile invalid ``*.py`` files, template files ending with ``.py-tpl`` will be renamed to ``.py``. -.. _source: https://github.com/django/django/tree/master/django/conf/app_template/ - ``startproject`` ---------------- @@ -1270,9 +1267,9 @@ files is: Creates a Django project directory structure for the given project name in the current directory or the given destination. -By default, the new directory contains ``manage.py`` and a project package -(containing a ``settings.py`` and other files). See the `template source`_ for -details. +By default, :source:`the new directory ` contains +``manage.py`` and a project package (containing a ``settings.py`` and other +files). If only the project name is given, both the project directory and project package will be named ```` and the project directory @@ -1315,8 +1312,6 @@ The :class:`template context ` used is: Please also see the :ref:`rendering warning ` as mentioned for :djadmin:`startapp`. -.. _`template source`: https://github.com/django/django/tree/master/django/conf/project_template/ - ``test`` -------- diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index ec733b6bef..e7a294923f 100644 --- a/docs/ref/settings.txt +++ b/docs/ref/settings.txt @@ -1160,8 +1160,6 @@ requests being returned as "Bad Request (400)". The default :file:`settings.py` file created by :djadmin:`django-admin startproject ` sets ``DEBUG = True`` for convenience. -.. _django/views/debug.py: https://github.com/django/django/blob/master/django/views/debug.py - .. setting:: DEBUG_PROPAGATE_EXCEPTIONS ``DEBUG_PROPAGATE_EXCEPTIONS`` @@ -1825,9 +1823,7 @@ deletes the one. Default: A list of all available languages. This list is continually growing and including a copy here would inevitably become rapidly out of date. You can see the current list of translated languages by looking in -``django/conf/global_settings.py`` (or view the `online source`_). - -.. _online source: https://github.com/django/django/blob/master/django/conf/global_settings.py +:source:`django/conf/global_settings.py`. The list is a list of two-tuples in the format (:term:`language code`, ``language name``) -- for example, @@ -1858,11 +1854,7 @@ Here's a sample settings file:: Default: A list of all language codes from the :setting:`LANGUAGES` setting that are written right-to-left. You can see the current list of these languages -by looking in ``django/conf/global_settings.py`` (or view the `online -source`_). - -.. _online source: https://github.com/django/django/blob/master/django/conf/global_settings.py - +by looking in :source:`django/conf/global_settings.py`. The list contains :term:`language codes` for languages that are written right-to-left. @@ -1906,9 +1898,7 @@ errors to an email log handler when :setting:`DEBUG` is ``False``. See also :ref:`configuring-logging`. You can see the default logging configuration by looking in -``django/utils/log.py`` (or view the `online source`__). - -__ https://github.com/django/django/blob/master/django/utils/log.py +:source:`django/utils/log.py`. .. setting:: LOGGING_CONFIG diff --git a/docs/ref/templates/api.txt b/docs/ref/templates/api.txt index 5bd55cff65..86ef097749 100644 --- a/docs/ref/templates/api.txt +++ b/docs/ref/templates/api.txt @@ -1026,9 +1026,8 @@ Loader methods .. admonition:: Building your own - For examples, `read the source code for Django's built-in loaders`_. - -.. _read the source code for Django's built-in loaders: https://github.com/django/django/tree/master/django/template/loaders + For examples, read the :source:`source code for Django's built-in loaders + `. .. currentmodule:: django.template.base diff --git a/docs/topics/auth/customizing.txt b/docs/topics/auth/customizing.txt index cc0c791f59..87988873a4 100644 --- a/docs/topics/auth/customizing.txt +++ b/docs/topics/auth/customizing.txt @@ -204,14 +204,12 @@ Notice that in addition to the same arguments given to the associated all take the user object, which may be an anonymous user, as an argument. A full authorization implementation can be found in the ``ModelBackend`` class -in `django/contrib/auth/backends.py`_, which is the default backend and queries -the ``auth_permission`` table most of the time. If you wish to provide +in :source:`django/contrib/auth/backends.py`, which is the default backend and +queries the ``auth_permission`` table most of the time. If you wish to provide custom behavior for only part of the backend API, you can take advantage of Python inheritance and subclass ``ModelBackend`` instead of implementing the complete API in a custom backend. -.. _django/contrib/auth/backends.py: https://github.com/django/django/blob/master/django/contrib/auth/backends.py - .. _anonymous_auth: Authorization for anonymous users diff --git a/docs/topics/db/queries.txt b/docs/topics/db/queries.txt index bb8b755297..bcdaaea359 100644 --- a/docs/topics/db/queries.txt +++ b/docs/topics/db/queries.txt @@ -867,10 +867,8 @@ precede the definition of any keyword arguments. For example:: .. seealso:: - The `OR lookups examples`_ in the Django unit tests show some possible uses - of ``Q``. - - .. _OR lookups examples: https://github.com/django/django/blob/master/tests/or_lookups/tests.py + The :source:`OR lookups examples ` in Django's + unit tests show some possible uses of ``Q``. Comparing objects =================