diff options
Diffstat (limited to 'docs/internals/contributing/writing-documentation.txt')
| -rw-r--r-- | docs/internals/contributing/writing-documentation.txt | 183 |
1 files changed, 109 insertions, 74 deletions
diff --git a/docs/internals/contributing/writing-documentation.txt b/docs/internals/contributing/writing-documentation.txt index 4783d2eef7..763039e61a 100644 --- a/docs/internals/contributing/writing-documentation.txt +++ b/docs/internals/contributing/writing-documentation.txt @@ -18,26 +18,21 @@ Documentation changes generally come in two forms: This section explains how writers can craft their documentation changes in the most useful and least error-prone ways. -Getting the raw documentation -============================= +The Django documentation process +================================ Though Django's documentation is intended to be read as HTML at -https://docs.djangoproject.com/, we edit it as a collection of text files for -maximum flexibility. These files live in the top-level :source:`docs/` directory of a -Django release. +https://docs.djangoproject.com/, we edit it as a collection of plain text files +written in the reStructuredText markup language for maximum flexibility. -If you'd like to start contributing to our docs, get the development version of -Django from the source code repository -(see :ref:`installing-development-version`). The development version has the +We work from the development version of the repository because it has the latest-and-greatest documentation, just as it has the latest-and-greatest code. + We also backport documentation fixes and improvements, at the discretion of the -merger, to the last release branch. That's because it's highly advantageous to +merger, to the last release branch. This is because it's advantageous to have the docs for the last release be up-to-date and correct (see :ref:`differences-between-doc-versions`). -Getting started with Sphinx -=========================== - Django's documentation uses the Sphinx__ documentation system, which in turn is based on docutils__. The basic idea is that lightly-formatted plain-text documentation is transformed into HTML, PDF, and any other output format. @@ -45,26 +40,10 @@ documentation is transformed into HTML, PDF, and any other output format. __ https://www.sphinx-doc.org/ __ https://docutils.sourceforge.io/ -To build the documentation locally, install Sphinx: - -.. console:: - - $ python -m pip install Sphinx - -Then from the ``docs`` directory, build the HTML: - -.. console:: - - $ make html - -To get started contributing, you'll want to read the :ref:`reStructuredText -reference <sphinx:rst-index>`. - -Your locally-built documentation will be accessible at -``docs/_build/html/index.html`` and it can be viewed in any web browser, though -it will be themed differently than the documentation at -`docs.djangoproject.com <https://docs.djangoproject.com/>`_. This is OK! If -your changes look good on your local machine, they'll look good on the website. +Sphinx includes a ``sphinx-build`` command for turning reStructuredText into +other formats, e.g., HTML and PDF. This command is configurable, but the Django +documentation includes a ``Makefile`` that provides a shorter ``make html`` +command. How the documentation is organized ================================== @@ -117,6 +96,104 @@ The documentation is organized into several categories: hesitate to refer the reader back to the appropriate tutorial rather than repeat the same material. +How to start contributing documentation +======================================= + +Clone the Django repository to your local machine +------------------------------------------------- + +If you'd like to start contributing to our docs, get the development version of +Django from the source code repository (see +:ref:`installing-development-version`): + +.. console:: + + $ git clone https://github.com/django/django.git + +If you're planning to submit these changes, you might find it useful to make a +fork of the Django repository and clone this fork instead. + +Set up a virtual environment and install dependencies +----------------------------------------------------- + +Create and activate a virtual environment, then install the dependencies: + +.. code-block:: shell + + $ python -m venv .venv + $ source .venv/bin/activate + $ python -m pip install -r docs/requirements.txt + +Build the documentation locally +------------------------------- + +We can build HTML output from the ``docs`` directory: + +.. console:: + + $ cd docs + $ make html + +Your locally-built documentation will be accessible at +``_build/html/index.html`` and it can be viewed in any web browser, though it +will be themed differently than the documentation at +`docs.djangoproject.com <https://docs.djangoproject.com/>`_. This is OK! If +your changes look good on your local machine, they'll look good on the website. + +Making edits to the documentation +--------------------------------- + +The source files are ``.txt`` files located in the ``docs/`` directory. + +These files are written in the reStructuredText markup language. To learn the +markup, see the :ref:`reStructuredText reference <sphinx:rst-index>`. + +To edit this page, for example, we would edit the file +:source:`docs/internals/contributing/writing-documentation.txt` and rebuild the +HTML with ``make html``. + +.. _documentation-spelling-check: + +Spelling check +-------------- + +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 +``docs`` directory, run ``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 +one of the following: + +* Surround inline code or brand/technology names with double grave accents + (``). +* Find synonyms that the spell checker recognizes. +* 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). + +.. _documentation-link-check: + +Link check +---------- + +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 +links in the documentation are working. From the ``docs`` directory, run ``make +linkcheck``. Output is printed to the terminal, but can also be found in +``_build/linkcheck/output.txt`` and ``_build/linkcheck/output.json``. + +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 +matched ignore rules in the configuration. + +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/``. + Writing style ============= @@ -524,48 +601,6 @@ example: That's basically how everything fits together. -.. _documentation-spelling-check: - -Spelling check -============== - -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 -``docs`` directory, run ``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 -one of the following: - -* Surround inline code or brand/technology names with double grave accents - (``). -* Find synonyms that the spell checker recognizes. -* 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). - -.. _documentation-link-check: - -Link check -========== - -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 -links in the documentation are working. From the ``docs`` directory, run ``make -linkcheck``. Output is printed to the terminal, but can also be found in -``_build/linkcheck/output.txt`` and ``_build/linkcheck/output.json``. - -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 -matched ignore rules in the configuration. - -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/``. - Translating documentation ========================= |