1
0
mirror of https://github.com/django/django.git synced 2025-10-24 14:16:09 +00:00

Refs #36485 -- Rewrapped docs to 79 columns line length.

Lines in the docs files were manually adjusted to conform to the
79 columns limit per line (plus newline), improving readability and
consistency across the content.
This commit is contained in:
David Smith
2025-07-25 10:24:17 +01:00
committed by nessita
parent 4286a23df6
commit f81e6e3a53
230 changed files with 3250 additions and 2914 deletions

View File

@@ -4,7 +4,8 @@ Committing code
This section is addressed to the mergers and to anyone interested in knowing
how code gets committed into Django. If you're a community member who wants to
contribute code to Django, look at :doc:`writing-code/working-with-git` instead.
contribute code to Django, look at :doc:`writing-code/working-with-git`
instead.
.. _handling-pull-requests:

View File

@@ -438,10 +438,10 @@ Next, we mark the current point in history as being "bad" since the test fails:
Now, we need to find a point in git history before the regression was
introduced (i.e. a point where the test passes). Use something like
``git checkout HEAD~100`` to check out an earlier revision (100 commits earlier,
in this case). Check if the test fails. If so, mark that point as "bad"
(``git bisect bad``), then check out an earlier revision and recheck. Once you
find a revision where your test passes, mark it as "good":
``git checkout HEAD~100`` to check out an earlier revision (100 commits
earlier, in this case). Check if the test fails. If so, mark that point as
"bad" (``git bisect bad``), then check out an earlier revision and recheck.
Once you find a revision where your test passes, mark it as "good":
.. code-block:: shell

View File

@@ -96,13 +96,12 @@ Python style
* In docstrings, follow the style of existing docstrings and :pep:`257`.
* In tests, use
:meth:`~django.test.SimpleTestCase.assertRaisesMessage` and
:meth:`~django.test.SimpleTestCase.assertWarnsMessage`
instead of :meth:`~unittest.TestCase.assertRaises` and
:meth:`~unittest.TestCase.assertWarns` so you can check the
exception or warning message. Use :meth:`~unittest.TestCase.assertRaisesRegex`
and :meth:`~unittest.TestCase.assertWarnsRegex` only if you need regular
* In tests, use :meth:`~django.test.SimpleTestCase.assertRaisesMessage` and
:meth:`~django.test.SimpleTestCase.assertWarnsMessage` instead of
:meth:`~unittest.TestCase.assertRaises` and
:meth:`~unittest.TestCase.assertWarns` so you can check the exception or
warning message. Use :meth:`~unittest.TestCase.assertRaisesRegex` and
:meth:`~unittest.TestCase.assertWarnsRegex` only if you need regular
expression matching.
Use :meth:`assertIs(…, True/False)<unittest.TestCase.assertIs>` for testing
@@ -149,9 +148,10 @@ Imports
* Put imports in these groups: future, standard library, third-party libraries,
other Django components, local Django component, try/excepts. Sort lines in
each group alphabetically by the full module name. Place all ``import module``
statements before ``from module import objects`` in each section. Use absolute
imports for other Django components and relative imports for local components.
each group alphabetically by the full module name. Place all
``import module`` statements before ``from module import objects`` in each
section. Use absolute imports for other Django components and relative
imports for local components.
* On each line, alphabetize the items with the upper case items grouped before
the lowercase items.

View File

@@ -17,8 +17,8 @@ Code style
for indentation, but there are some exceptions.
* When naming variables, use ``camelCase`` instead of ``underscore_case``.
Different JavaScript files sometimes use a different code style. Please try to
conform to the code style of each file.
Different JavaScript files sometimes use a different code style. Please try
to conform to the code style of each file.
* Use the `ESLint`_ code linter to check your code for bugs and style errors.
ESLint will be run when you run the JavaScript tests. We also recommended
@@ -89,8 +89,8 @@ The JavaScript tests may be run from a web browser or from the command line.
Testing from a web browser
~~~~~~~~~~~~~~~~~~~~~~~~~~
To run the tests from a web browser, open up :source:`js_tests/tests.html` in your
browser.
To run the tests from a web browser, open up :source:`js_tests/tests.html` in
your browser.
To measure code coverage when running the tests, you need to view that file
over HTTP. To view code coverage:

View File

@@ -204,9 +204,12 @@ whether to accept it.
Some examples of DEPs that have been approved and fully implemented:
* `DEP 181: ORM Expressions <https://github.com/django/deps/blob/main/final/0181-orm-expressions.rst>`_
* `DEP 182: Multiple Template Engines <https://github.com/django/deps/blob/main/final/0182-multiple-template-engines.rst>`_
* `DEP 201: Simplified routing syntax <https://github.com/django/deps/blob/main/final/0201-simplified-routing-syntax.rst>`_
* `DEP 181: ORM Expressions
<https://github.com/django/deps/blob/main/final/0181-orm-expressions.rst>`_
* `DEP 182: Multiple Template Engines
<https://github.com/django/deps/blob/main/final/0182-multiple-template-engines.rst>`_
* `DEP 201: Simplified routing syntax
<https://github.com/django/deps/blob/main/final/0201-simplified-routing-syntax.rst>`_
.. _Django Forum: https://forum.djangoproject.com/
.. _Django Enhancement Proposals: https://github.com/django/deps
@@ -226,19 +229,19 @@ There are a couple of reasons that code in Django might be deprecated:
no longer needs to support the older version of Python that doesn't include
the library, the library will be deprecated in Django.
As the :ref:`deprecation policy<internal-release-deprecation-policy>` describes,
the first release of Django that deprecates a feature (``A.B``) should raise a
``RemovedInDjangoXXWarning`` (where XX is the Django version where the feature
will be removed) when the deprecated feature is invoked. Assuming we have good
test coverage, these warnings are converted to errors when :ref:`running the
test suite <running-unit-tests>` with warnings enabled:
As the :ref:`deprecation policy<internal-release-deprecation-policy>`
describes, the first release of Django that deprecates a feature (``A.B``)
should raise a ``RemovedInDjangoXXWarning`` (where XX is the Django version
where the feature will be removed) when the deprecated feature is invoked.
Assuming we have good test coverage, these warnings are converted to errors
when :ref:`running the test suite <running-unit-tests>` with warnings enabled:
``python -Wa runtests.py``. Thus, when adding a ``RemovedInDjangoXXWarning``
you need to eliminate or silence any warnings generated when running the tests.
The first step is to remove any use of the deprecated behavior by Django itself.
Next you can silence warnings in tests that actually test the deprecated
behavior by using the ``ignore_warnings`` decorator, either at the test or class
level:
The first step is to remove any use of the deprecated behavior by Django
itself. Next you can silence warnings in tests that actually test the
deprecated behavior by using the ``ignore_warnings`` decorator, either at the
test or class level:
#) In a particular test::
@@ -305,8 +308,9 @@ Finally, there are a couple of updates to Django's documentation to make:
applicable, to the current release notes (``docs/releases/A.B.txt``) under
the "Features deprecated in A.B" heading.
#) Add an entry in the deprecation timeline (``docs/internals/deprecation.txt``)
under the appropriate version describing what code will be removed.
#) Add an entry in the deprecation timeline
(``docs/internals/deprecation.txt``) under the appropriate version
describing what code will be removed.
Once you have completed these steps, you are finished with the deprecation.
In each :term:`feature release <Feature release>`, all
@@ -402,10 +406,10 @@ Bugs
* Is there a proper regression test (the test should fail before the fix
is applied)?
* If it's a bug that :ref:`qualifies for a backport <supported-versions-policy>`
to the stable version of Django, is there a release note in
``docs/releases/A.B.C.txt``? Bug fixes that will be applied only to the main
branch don't need a release note.
* If it's a bug that :ref:`qualifies for a backport
<supported-versions-policy>` to the stable version of Django, is there a
release note in ``docs/releases/A.B.C.txt``? Bug fixes that will be applied
only to the main branch don't need a release note.
New Features
------------

View File

@@ -398,9 +398,9 @@ and also excludes several directories not relevant to the results
Contrib apps
============
Tests for contrib apps can be found in the :source:`tests/` directory, typically
under ``<app_name>_tests``. For example, tests for ``contrib.auth`` are located
in :source:`tests/auth_tests`.
Tests for contrib apps can be found in the :source:`tests/` directory,
typically under ``<app_name>_tests``. For example, tests for ``contrib.auth``
are located in :source:`tests/auth_tests`.
.. _troubleshooting-unit-tests:

View File

@@ -205,8 +205,8 @@ All Python code blocks should be formatted using the :pypi:`blacken-docs`
auto-formatter. This is automatically run by the :ref:`pre-commit hook
<coding-style-pre-commit>` if configured.
The check can also be run manually: provided that ``blacken-docs`` is installed,
run the following command from the ``docs`` directory:
The check can also be run manually: provided that ``blacken-docs`` is
installed, run the following command from the ``docs`` directory:
.. console::
@@ -245,8 +245,8 @@ Entries that have a status of "broken" need to be fixed. Those that have a
status of "redirected" may need to be updated to point to the canonical
location, e.g. the scheme has changed ``http://`` → ``https://``. In certain
cases, we do not want to update a "redirected" link, e.g. a rewrite to always
point to the latest or stable version of the documentation, e.g. ``/en/stable/`` →
``/en/3.2/``.
point to the latest or stable version of the documentation, e.g.
``/en/stable/`` → ``/en/3.2/``.
Writing style
=============
@@ -523,12 +523,12 @@ General improvements or other changes to the APIs that should be emphasized
should use the "``.. versionchanged:: X.Y``" directive (with the same format
as the ``versionadded`` mentioned above.
These ``versionadded`` and ``versionchanged`` blocks should be "self-contained."
In other words, since we only keep these annotations around for two releases,
it's nice to be able to remove the annotation and its contents without having
to reflow, reindent, or edit the surrounding text. For example, instead of
putting the entire description of a new or changed feature in a block, do
something like this:
These ``versionadded`` and ``versionchanged`` blocks should be
"self-contained." In other words, since we only keep these annotations around
for two releases, it's nice to be able to remove the annotation and its
contents without having to reflow, reindent, or edit the surrounding text. For
example, instead of putting the entire description of a new or changed feature
in a block, do something like this:
.. code-block:: rst
@@ -659,12 +659,12 @@ you'd like to help translate the documentation into another language.
``django-admin`` man page
=========================
Sphinx can generate a manual page for the
:doc:`django-admin </ref/django-admin>` command. This is configured in
``docs/conf.py``. Unlike other documentation output, this man page should be
included in the Django repository and the releases as
``docs/man/django-admin.1``. There isn't a need to update this file when
updating the documentation, as it's updated once as part of the release process.
Sphinx can generate a manual page for the :doc:`django-admin
</ref/django-admin>` command. This is configured in ``docs/conf.py``. Unlike
other documentation output, this man page should be included in the Django
repository and the releases as ``docs/man/django-admin.1``. There isn't a need
to update this file when updating the documentation, as it's updated once as
part of the release process.
To generate an updated version of the man page, in the ``docs`` directory, run: