From a9337b4add01e50ed8ff8d3ef44099a08cba475c Mon Sep 17 00:00:00 2001 From: Nick Pope Date: Thu, 30 Apr 2020 10:30:11 +0100 Subject: [PATCH] Used :pep: role in various docs. --- docs/howto/deployment/wsgi/index.txt | 8 ++++---- docs/internals/contributing/writing-documentation.txt | 4 ++++ docs/ref/files/uploads.txt | 8 +++----- docs/ref/request-response.txt | 7 +++---- docs/releases/1.6.txt | 2 +- docs/releases/1.8.txt | 8 +++----- docs/topics/db/transactions.txt | 5 ++--- 7 files changed, 20 insertions(+), 22 deletions(-) diff --git a/docs/howto/deployment/wsgi/index.txt b/docs/howto/deployment/wsgi/index.txt index c7416b84fdc..fae2d69980f 100644 --- a/docs/howto/deployment/wsgi/index.txt +++ b/docs/howto/deployment/wsgi/index.txt @@ -70,8 +70,10 @@ If this variable isn't set, the default :file:`wsgi.py` sets it to Applying WSGI middleware ======================== -To apply `WSGI middleware`_ you can wrap the application object. For instance -you could add these lines at the bottom of :file:`wsgi.py`:: +To apply :pep:`WSGI middleware +<3333#middleware-components-that-play-both-sides>` you can wrap the application +object. For instance you could add these lines at the bottom of +:file:`wsgi.py`:: from helloworld.wsgi import HelloWorldApplication application = HelloWorldApplication(application) @@ -79,5 +81,3 @@ you could add these lines at the bottom of :file:`wsgi.py`:: You could also replace the Django WSGI application with a custom WSGI application that later delegates to the Django WSGI application, if you want to combine a Django application with a WSGI application of another framework. - -.. _`WSGI middleware`: https://www.python.org/dev/peps/pep-3333/#middleware-components-that-play-both-sides diff --git a/docs/internals/contributing/writing-documentation.txt b/docs/internals/contributing/writing-documentation.txt index 5036f30fe02..91b81e46731 100644 --- a/docs/internals/contributing/writing-documentation.txt +++ b/docs/internals/contributing/writing-documentation.txt @@ -239,6 +239,10 @@ documentation: section if possible. For example, use ``:rfc:`2324#section-2.3.2``` or ``:rfc:`Custom link text <2324#section-2.3.2>```. +* Use :rst:role:`:pep:` to reference a Python Enhancement Proposal (PEP) + and try to link to the relevant section if possible. For example, use + ``:pep:`20#easter-egg``` or ``:pep:`Easter Egg <20#easter-egg>```. + Django-specific markup ====================== diff --git a/docs/ref/files/uploads.txt b/docs/ref/files/uploads.txt index 0021800a641..4ce4eb991ad 100644 --- a/docs/ref/files/uploads.txt +++ b/docs/ref/files/uploads.txt @@ -76,11 +76,9 @@ Here are some useful attributes of ``UploadedFile``: for line in uploadedfile: do_something_with(line) - Lines are split using `universal newlines`_. The following are recognized - as ending a line: the Unix end-of-line convention ``'\n'``, the Windows - convention ``'\r\n'``, and the old Macintosh convention ``'\r'``. - - .. _universal newlines: https://www.python.org/dev/peps/pep-0278 + Lines are split using :pep:`universal newlines <278>`. The following are + recognized as ending a line: the Unix end-of-line convention ``'\n'``, the + Windows convention ``'\r\n'``, and the old Macintosh convention ``'\r'``. Subclasses of ``UploadedFile`` include: diff --git a/docs/ref/request-response.txt b/docs/ref/request-response.txt index ad57038e5ae..17c0f303354 100644 --- a/docs/ref/request-response.txt +++ b/docs/ref/request-response.txt @@ -1161,8 +1161,9 @@ Attributes .. class:: FileResponse(open_file, as_attachment=False, filename='', **kwargs) :class:`FileResponse` is a subclass of :class:`StreamingHttpResponse` - optimized for binary files. It uses `wsgi.file_wrapper`_ if provided by the - wsgi server, otherwise it streams the file out in small chunks. + optimized for binary files. It uses :pep:`wsgi.file_wrapper + <3333#optional-platform-specific-file-handling>` if provided by the wsgi + server, otherwise it streams the file out in small chunks. If ``as_attachment=True``, the ``Content-Disposition`` header is set to ``attachment``, which asks the browser to offer the file to the user as a @@ -1178,8 +1179,6 @@ Attributes The ``Content-Length`` and ``Content-Type`` headers are automatically set when they can be guessed from contents of ``open_file``. -.. _wsgi.file_wrapper: https://www.python.org/dev/peps/pep-3333/#optional-platform-specific-file-handling - ``FileResponse`` accepts any file-like object with binary content, for example a file open in binary mode like so:: diff --git a/docs/releases/1.6.txt b/docs/releases/1.6.txt index 71457f15f67..304c12c3249 100644 --- a/docs/releases/1.6.txt +++ b/docs/releases/1.6.txt @@ -173,7 +173,7 @@ Minor features * In addition to :lookup:`year`, :lookup:`month` and :lookup:`day`, the ORM now supports :lookup:`hour`, :lookup:`minute` and :lookup:`second` lookups. -* Django now wraps all PEP-249 exceptions. +* Django now wraps all :pep:`249` exceptions. * The default widgets for :class:`~django.forms.EmailField`, :class:`~django.forms.URLField`, :class:`~django.forms.IntegerField`, diff --git a/docs/releases/1.8.txt b/docs/releases/1.8.txt index 38451768277..ab57349e090 100644 --- a/docs/releases/1.8.txt +++ b/docs/releases/1.8.txt @@ -1123,11 +1123,9 @@ Miscellaneous check framework (unless you pass it ``skip_checks=False``). * When iterating over lines, :class:`~django.core.files.File` now uses - `universal newlines`_. The following are recognized as ending a line: the - Unix end-of-line convention ``'\n'``, the Windows convention ``'\r\n'``, and - the old Macintosh convention ``'\r'``. - - .. _universal newlines: https://www.python.org/dev/peps/pep-0278 + :pep:`universal newlines <278>`. The following are recognized as ending a + line: the Unix end-of-line convention ``'\n'``, the Windows convention + ``'\r\n'``, and the old Macintosh convention ``'\r'``. * The Memcached cache backends ``MemcachedCache`` and ``PyLibMCCache`` will delete a key if ``set()`` fails. This is necessary to ensure the ``cache_db`` diff --git a/docs/topics/db/transactions.txt b/docs/topics/db/transactions.txt index 40a36e777d1..44a21e5ee24 100644 --- a/docs/topics/db/transactions.txt +++ b/docs/topics/db/transactions.txt @@ -369,8 +369,8 @@ etc.), this should be fine. If it's not (if your follow-up action is so critical that its failure should mean the failure of the transaction itself), then you don't want to use the :func:`on_commit` hook. Instead, you may want `two-phase commit`_ such as the :ref:`psycopg Two-Phase Commit protocol support -` and the `optional Two-Phase Commit Extensions in the Python -DB-API specification`_. +` and the :pep:`optional Two-Phase Commit Extensions in the +Python DB-API specification <249#optional-two-phase-commit-extensions>`. Callbacks are not run until autocommit is restored on the connection following the commit (because otherwise any queries done in a callback would open an @@ -387,7 +387,6 @@ autocommit is disabled and you are not within an atomic block will result in an error. .. _two-phase commit: https://en.wikipedia.org/wiki/Two-phase_commit_protocol -.. _optional Two-Phase Commit Extensions in the Python DB-API specification: https://www.python.org/dev/peps/pep-0249/#optional-two-phase-commit-extensions Use in tests ------------