mirrors/django
1
0
Fork 0
mirror of https://github.com/django/django.git synced 2025-08-21 01:09:13 +00:00
Code Issues 32 Releases Wiki Activity

Refs #34140 -- Added dedicated code block formatting section in docs/internals/contributing/writing-documentation.txt.

Browse Source
This commit is contained in:
David Smith 2025-06-25 16:43:04 +01:00 committed by nessita
parent 6142e3f347
commit cba7328196
1 changed files with 19 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -177,6 +177,25 @@ one of the following:
* If, and only if, you are sure the word you are using is correct - add it * If, and only if, you are sure the word you are using is correct - add it
to ``docs/spelling_wordlist`` (please keep the list in alphabetical order). to ``docs/spelling_wordlist`` (please keep the list in alphabetical order).
.. _documentation-code-block-format-check:
Code block format check
-----------------------
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:
.. console::
$ make black
The formatter will report any issues by printing them to the terminal and will
reformat code blocks where possible.
.. _documentation-link-check: .. _documentation-link-check:
Link check Link check
@ -305,10 +324,6 @@ documentation:
"last bit" of that path. So ``:mod:`~django.contrib.auth``` will "last bit" of that path. So ``:mod:`~django.contrib.auth``` will
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`
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.