mirrors/django
1
0
Fork 0
mirror of https://github.com/django/django.git synced 2025-03-13 19:00:45 +00:00
Code Issues 32 Releases Wiki Activity

Improved the writing documentation contributing guide.

Browse Source
This commit is contained in:
Paolo Melchiorre 2024-10-25 15:26:46 +02:00 committed by Sarah Boyce
parent 4c3897bb15
commit b5669f08bc
1 changed files with 37 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
docs/internals/contributing/writing-documentation.txt
View File

@ -159,9 +159,14 @@ Spelling check
Before you commit your docs, it's a good idea to run the spelling checker. Before you commit your docs, it's a good idea to run the spelling checker.
You'll need to install :pypi:`sphinxcontrib-spelling` first. Then from the You'll need to install :pypi:`sphinxcontrib-spelling` first. Then from the
``docs`` directory, run ``make spelling``. Wrong words (if any) along with the ``docs`` directory, run:
file and line number where they occur will be saved to
``_build/spelling/output.txt``. .. console::
$ make spelling
Wrong words (if any) along with the file and line number where they occur will
be saved to ``_build/spelling/output.txt``.
If you encounter false-positives (error output that actually is correct), do If you encounter false-positives (error output that actually is correct), do
one of the following: one of the following:
@ -179,10 +184,21 @@ Link check
Links in documentation can become broken or changed such that they are no Links in documentation can become broken or changed such that they are no
longer the canonical link. Sphinx provides a builder that can check whether the longer the canonical link. Sphinx provides a builder that can check whether the
links in the documentation are working. From the ``docs`` directory, run ``make links in the documentation are working. From the ``docs`` directory, run:
linkcheck``. Output is printed to the terminal, but can also be found in
.. console::
$ make linkcheck
Output is printed to the terminal, but can also be found in
``_build/linkcheck/output.txt`` and ``_build/linkcheck/output.json``. ``_build/linkcheck/output.txt`` and ``_build/linkcheck/output.json``.
.. warning::
The execution of the command requires an internet connection and takes
several minutes to complete, because the command tests all the links
that are found in the documentation.
Entries that have a status of "working" are fine, those that are "unchecked" or Entries that have a status of "working" are fine, those that are "unchecked" or
"ignored" have been skipped because they either cannot be checked or have "ignored" have been skipped because they either cannot be checked or have
matched ignore rules in the configuration. matched ignore rules in the configuration.
@ -290,7 +306,8 @@ documentation:
display a link with the title "auth". display a link with the title "auth".
* All Python code blocks should be formatted using the :pypi:`blacken-docs` * All Python code blocks should be formatted using the :pypi:`blacken-docs`
auto-formatter. This will be run by ``pre-commit`` if that is configured. auto-formatter. This will be run by :ref:`pre-commit
<coding-style-pre-commit>` if that is configured.
* Use :mod:`~sphinx.ext.intersphinx` to reference Python's and Sphinx' * Use :mod:`~sphinx.ext.intersphinx` to reference Python's and Sphinx'
documentation. documentation.
@ -324,8 +341,9 @@ documentation:
Five Five
^^^^ ^^^^
* Use :rst:role:`:rfc:<rfc>` to reference RFC and try to link to the relevant * Use :rst:role:`:rfc:<rfc>` to reference a Request for Comments (RFC) and
section if possible. For example, use ``:rfc:`2324#section-2.3.2``` or try to link to the relevant section if possible. For example, use
``:rfc:`2324#section-2.3.2``` or
``:rfc:`Custom link text <2324#section-2.3.2>```. ``:rfc:`Custom link text <2324#section-2.3.2>```.
* Use :rst:role:`:pep:<pep>` to reference a Python Enhancement Proposal (PEP) * Use :rst:role:`:pep:<pep>` to reference a Python Enhancement Proposal (PEP)
@ -339,6 +357,9 @@ documentation:
also need to define a reference to the documentation for that environment also need to define a reference to the documentation for that environment
variable using :rst:dir:`.. envvar:: <envvar>`. variable using :rst:dir:`.. envvar:: <envvar>`.
* Use :rst:role:`:cve:<cve>` to reference a Common Vulnerabilities and
Exposures (CVE) identifier. For example, use ``:cve:`2019-14232```.
Django-specific markup Django-specific markup
====================== ======================
@ -518,7 +539,7 @@ Minimizing images
Optimize image compression where possible. For PNG files, use OptiPNG and Optimize image compression where possible. For PNG files, use OptiPNG and
AdvanceCOMP's ``advpng``: AdvanceCOMP's ``advpng``:
.. code-block:: console .. console::
$ cd docs $ cd docs
$ optipng -o7 -zm1-9 -i0 -strip all `find . -type f -not -path "./_build/*" -name "*.png"` $ optipng -o7 -zm1-9 -i0 -strip all `find . -type f -not -path "./_build/*" -name "*.png"`
@ -619,6 +640,10 @@ included in the Django repository and the releases as
``docs/man/django-admin.1``. There isn't a need to update this file when ``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. updating the documentation, as it's updated once as part of the release process.
To generate an updated version of the man page, run ``make man`` in the To generate an updated version of the man page, in the ``docs`` directory, run:
``docs`` directory. The new man page will be written in
``docs/_build/man/django-admin.1``. .. console::
$ make man
The new man page will be written in ``docs/_build/man/django-admin.1``.