IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Update the contributor's guide

Browse Source
This commit is contained in:
Adam Turner 2024-07-24 15:03:10 +01:00
parent 3222415785
commit 7b6d448517
1 changed files with 140 additions and 106 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

246
doc/internals/contributing.rst
View File

@ -7,6 +7,7 @@ feature requests, writing new documentation or submitting patches for new or
fixed behavior. This guide serves to illustrate how you can get started with fixed behavior. This guide serves to illustrate how you can get started with
this. this.
Get help Get help
-------- --------
@ -15,6 +16,11 @@ The Sphinx community maintains a number of mailing lists and IRC channels.
Stack Overflow with tag `python-sphinx`_ Stack Overflow with tag `python-sphinx`_
Questions and answers about use and development. Questions and answers about use and development.
`GitHub Discussions Q&A`__
Question-and-answer style forum for discussions.
__ https://github.com/orgs/sphinx-doc/discussions/categories/q-a
sphinx-users <sphinx-users@googlegroups.com> sphinx-users <sphinx-users@googlegroups.com>
Mailing list for user support. Mailing list for user support.
@ -26,88 +32,84 @@ sphinx-dev <sphinx-dev@googlegroups.com>
.. _python-sphinx: https://stackoverflow.com/questions/tagged/python-sphinx .. _python-sphinx: https://stackoverflow.com/questions/tagged/python-sphinx
Bug Reports and Feature Requests Bug Reports and Feature Requests
-------------------------------- --------------------------------
If you have encountered a problem with Sphinx or have an idea for a new If you have encountered a problem with Sphinx or have an idea for a new
feature, please submit it to the `issue tracker`_ on GitHub or discuss it feature, please submit it to the `issue tracker`_ on GitHub.
on the `sphinx-dev`_ mailing list.
For bug reports, please include the output produced during the build process For bug reports, please include the output produced during the build process
and also the log file Sphinx creates after it encounters an unhandled and also the log file Sphinx creates after it encounters an unhandled
exception. The location of this file should be shown towards the end of the exception.
error message. The location of this file should be shown towards the end of the error message.
Please also include the output of :program:`sphinx-build --bug-report`.
Including or providing a link to the source files involved may help us fix the Including or providing a link to the source files involved may help us fix the
issue. If possible, try to create a minimal project that produces the error issue. If possible, try to create a minimal project that produces the error
and post that instead. and post that instead.
.. _`issue tracker`: https://github.com/sphinx-doc/sphinx/issues .. _`issue tracker`: https://github.com/sphinx-doc/sphinx/issues
.. _`sphinx-dev`: mailto:sphinx-dev@googlegroups.com
Contribute code Contribute code
--------------- ---------------
The Sphinx source code is managed using Git and is hosted on `GitHub`__. The The Sphinx source code is managed using Git and is `hosted on GitHub`_. The
recommended way for new contributors to submit code to Sphinx is to fork this recommended way for new contributors to submit code to Sphinx is to fork this
repository and submit a pull request after committing changes to their fork. repository and submit a pull request after committing changes to their fork.
The pull request will then need to be approved by one of the core developers The pull request will then need to be approved by one of the core developers
before it is merged into the main repository. before it is merged into the main repository.
.. __: https://github.com/sphinx-doc/sphinx .. _hosted on GitHub: https://github.com/sphinx-doc/sphinx
.. _contribute-get-started: .. _contribute-get-started:
Getting started Getting started
~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~
Before starting on a patch, we recommend checking for open issues or open a Before starting on a patch, we recommend checking for open issues
fresh issue to start a discussion around a feature idea or a bug. If you feel or opening a fresh issue to start a discussion around a feature idea or a bug.
uncomfortable or uncertain about an issue or your changes, feel free to email If you feel uncomfortable or uncertain about an issue or your changes,
the *sphinx-dev* mailing list. feel free to `start a discussion`_.
.. _start a discussion: https://github.com/orgs/sphinx-doc/discussions/
These are the basic steps needed to start developing on Sphinx. These are the basic steps needed to start developing on Sphinx.
#. Create an account on GitHub. #. Create an account on GitHub.
#. Fork the main Sphinx repository (`sphinx-doc/sphinx #. Fork_ the main Sphinx repository (`sphinx-doc/sphinx`_)
<https://github.com/sphinx-doc/sphinx>`_) using the GitHub interface. using the GitHub interface.
#. Clone the forked repository to your machine. :: .. _Fork: https://github.com/sphinx-doc/sphinx/fork
.. _sphinx-doc/sphinx: https://github.com/sphinx-doc/sphinx
git clone https://github.com/USERNAME/sphinx #. Clone the forked repository to your machine.
cd sphinx
#. Checkout the appropriate branch. .. code-block:: shell
Sphinx adopts Semantic Versioning 2.0.0 (refs: https://semver.org/ ). git clone https://github.com/<USERNAME>/sphinx
cd sphinx
For changes that preserves backwards-compatibility of API and features,
they should be included in the next MINOR release, use the ``A.x`` branch.
::
git checkout A.x
For incompatible or other substantial changes that should wait until the
next MAJOR release, use the ``master`` branch.
For urgent release, a new PATCH branch must be branched from the newest
release tag (see :doc:`release-process` for detail).
#. Setup a virtual environment. #. Setup a virtual environment.
This is not necessary for unit testing, thanks to ``tox``, but it is This is not necessary for unit testing, thanks to :program:`tox`,
necessary if you wish to run ``sphinx-build`` locally or run unit tests but it is necessary if you wish to run :program:`sphinx-build` locally
without the help of ``tox``:: or run unit tests without the help of :program:`tox`:
.. code-block:: shell
virtualenv ~/.venv virtualenv ~/.venv
. ~/.venv/bin/activate . ~/.venv/bin/activate
pip install -e . pip install -e .
#. Create a new working branch. Choose any name you like. :: #. Create a new working branch. Choose any name you like.
git checkout -b feature-xyz .. code-block:: shell
git switch -c feature-xyz
#. Hack, hack, hack. #. Hack, hack, hack.
@ -115,25 +117,31 @@ These are the basic steps needed to start developing on Sphinx.
the feature works as expected. the feature works as expected.
#. Add a bullet point to :file:`CHANGES.rst` if the fix or feature is not trivial #. Add a bullet point to :file:`CHANGES.rst` if the fix or feature is not trivial
(small doc updates, typo fixes), then commit:: (small doc updates, typo fixes), then commit:
git commit -m '#42: Add useful new feature that does this.' .. code-block:: shell
git commit -m '#42: Add useful new feature that does this.'
GitHub recognizes certain phrases that can be used to automatically GitHub recognizes certain phrases that can be used to automatically
update the issue tracker. For example:: update the issue tracker. For example:
git commit -m 'Closes #42: Fix invalid markup in docstring of Foo.bar.' .. code-block:: shell
git commit -m 'Closes #42: Fix invalid markup in docstring of Foo.bar.'
would close issue #42. would close issue #42.
#. Push changes in the branch to your forked repository on GitHub:: #. Push changes in the branch to your forked repository on GitHub:
git push origin feature-xyz .. code-block:: shell
#. Submit a pull request from your branch to the respective branch (``master`` git push origin feature-xyz
or ``A.x``).
#. Submit a pull request from your branch to the ``master`` branch.
#. Wait for a core developer or contributor to review your changes.
#. Wait for a core developer to review your changes.
Coding style Coding style
~~~~~~~~~~~~ ~~~~~~~~~~~~
@ -142,90 +150,101 @@ Please follow these guidelines when writing code for Sphinx:
* Try to use the same code style as used in the rest of the project. * Try to use the same code style as used in the rest of the project.
* For non-trivial changes, please update the :file:`CHANGES.rst` file. If your * For non-trivial changes, please update the :file:`CHANGES.rst` file.
changes alter existing behavior, please document this. If your changes alter existing behavior, please document this.
* New features should be documented. Include examples and use cases where * New features should be documented.
appropriate. If possible, include a sample that is displayed in the Include examples and use cases where appropriate.
generated output. If possible, include a sample that is displayed in the generated output.
* When adding a new configuration variable, be sure to document it and update * When adding a new configuration variable,
:file:`sphinx/cmd/quickstart.py` if it's important enough. be sure to :doc:`document it </usage/configuration>`
and update :file:`sphinx/cmd/quickstart.py` if it's important enough.
* Add appropriate unit tests. * Add appropriate unit tests.
Style and type checks can be run as follows:: Style and type checks can be run as follows:
.. code-block:: shell
ruff check . ruff check .
mypy sphinx/ mypy
Unit tests Unit tests
~~~~~~~~~~ ~~~~~~~~~~
Sphinx is tested using `pytest`__ for Python code and `Karma`__ for JavaScript. Sphinx is tested using pytest_ for Python code and Karma_ for JavaScript.
.. __: https://docs.pytest.org/en/latest/ .. _pytest: https://docs.pytest.org/en/latest/
.. __: https://karma-runner.github.io .. _Karma: https://karma-runner.github.io
To run Python unit tests, we recommend using ``tox``, which provides a number To run Python unit tests, we recommend using :program:`tox`, which provides a number
of targets and allows testing against multiple different Python environments: of targets and allows testing against multiple different Python environments:
* To list all possible targets:: * To list all possible targets:
tox -av .. code-block:: shell
* To run unit tests for a specific Python version, such as Python 3.12:: tox -av
tox -e py312 * To run unit tests for a specific Python version, such as Python 3.12:
* To run unit tests for a specific Python version and turn on deprecation .. code-block:: shell
warnings so they're shown in the test output::
PYTHONWARNINGS=error tox -e py312 tox -e py312
* Arguments to ``pytest`` can be passed via ``tox``, e.g., in order to run a * Arguments to :program:`pytest` can be passed via :program:`tox`,
particular test:: e.g., in order to run a particular test:
tox -e py312 tests/test_module.py::test_new_feature .. code-block:: shell
You can also test by installing dependencies in your local environment:: tox -e py312 tests/test_module.py::test_new_feature
pip install .[test] You can also test by installing dependencies in your local environment:
To run JavaScript tests, use ``npm``:: .. code-block:: shell
npm install pip install .[test]
npm run test
To run JavaScript tests, use :program:`npm`:
.. code-block:: shell
npm install
npm run test
.. tip:: .. tip::
``karma`` requires a Firefox binary to use as a test browser. :program:`karma` requires a Firefox binary to use as a test browser.
For Unix-based systems, you can specify the path to the Firefox binary using:: For Unix-based systems, you can specify the path to the Firefox binary using:
FIREFOX_BIN="/Applications/Firefox.app/Contents/MacOS/firefox" npm test .. code-block:: shell
New unit tests should be included in the ``tests`` directory where FIREFOX_BIN="/Applications/Firefox.app/Contents/MacOS/firefox" npm test
necessary:
New unit tests should be included in the :file:`tests/` directory where necessary:
* For bug fixes, first add a test that fails without your changes and passes * For bug fixes, first add a test that fails without your changes and passes
after they are applied. after they are applied.
* Tests that need a ``sphinx-build`` run should be integrated in one of the * Tests that need a :program:`sphinx-build` run should be integrated in one of the
existing test modules if possible. New tests that to ``@with_app`` and existing test modules if possible.
then ``build_all`` for a few assertions are not good since *the test suite
should not take more than a minute to run*. * Tests should be quick and only test the relevant components, as we aim that
*the test suite should not take more than a minute to run*.
In general, avoid using the ``app`` fixture and ``app.build()``
unless a full integration test is required.
.. versionadded:: 1.8 .. versionadded:: 1.8
Sphinx also runs JavaScript tests. Sphinx also runs JavaScript tests.
.. versionadded:: 1.6 .. versionadded:: 1.6
:py:mod:`!sphinx.testing` is added as a experimental.
``sphinx.testing`` is added as a experimental.
.. versionchanged:: 1.5.2 .. versionchanged:: 1.5.2
Sphinx was switched from nose to pytest. Sphinx was switched from nose to pytest.
.. todo:: The below belongs in the developer guide .. todo:: The below belongs in the developer guide
@ -237,7 +256,9 @@ test implementation.
How to use pytest fixtures that are provided by ``sphinx.testing``? You can How to use pytest fixtures that are provided by ``sphinx.testing``? You can
require ``'sphinx.testing.fixtures'`` in your test modules or ``conftest.py`` require ``'sphinx.testing.fixtures'`` in your test modules or ``conftest.py``
files like this:: files like this:
.. code-block:: python
pytest_plugins = 'sphinx.testing.fixtures' pytest_plugins = 'sphinx.testing.fixtures'
@ -248,8 +269,9 @@ and other ``test_*.py`` files under the ``tests`` directory.
Contribute documentation Contribute documentation
------------------------ ------------------------
Contributing to documentation involves modifying the source files found in the Contributing to documentation involves modifying the source files
``doc/`` folder. To get started, you should first follow :ref:`contribute-get-started`, found in the :file:`doc/` folder.
To get started, you should first follow :ref:`contribute-get-started`,
and then take the steps below to work with the documentation. and then take the steps below to work with the documentation.
The following sections describe how to get started with contributing The following sections describe how to get started with contributing
@ -257,21 +279,27 @@ documentation, as well as key aspects of a few different tools that we use.
.. todo:: Add a more extensive documentation contribution guide. .. todo:: Add a more extensive documentation contribution guide.
Build the documentation Build the documentation
~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~
To build the documentation, run the following command:: To build the documentation, run the following command:
sphinx-build -M html ./doc ./build/sphinx -W --keep-going .. code-block:: shell
sphinx-build -M html ./doc ./build/sphinx --fail-on-warning --keep-going
This will parse the Sphinx documentation's source files and generate HTML for This will parse the Sphinx documentation's source files and generate HTML for
you to preview in ``build/sphinx/html``. you to preview in :file:`build/sphinx/html`.
You can also build a **live version of the documentation** that you can preview You can also build a **live version of the documentation** that you can preview
in the browser. It will detect changes and reload the page any time you make in the browser. It will detect changes and reload the page any time you make
edits. To do so, run the following command:: edits. To do so, run the following command:
.. code-block:: shell
sphinx-autobuild ./doc ./build/sphinx/
sphinx-autobuild ./doc ./build/sphinx/
Translations Translations
~~~~~~~~~~~~ ~~~~~~~~~~~~
@ -281,7 +309,7 @@ locales. The translations are kept as gettext ``.po`` files translated from the
master template :file:`sphinx/locale/sphinx.pot`. master template :file:`sphinx/locale/sphinx.pot`.
Sphinx uses `Babel <https://babel.pocoo.org/en/latest/>`_ to extract messages Sphinx uses `Babel <https://babel.pocoo.org/en/latest/>`_ to extract messages
and maintain the catalog files. The ``utils`` directory contains a helper and maintain the catalog files. The :file:`utils` directory contains a helper
script, ``babel_runner.py``. script, ``babel_runner.py``.
* Use ``python babel_runner.py extract`` to update the ``.pot`` template. * Use ``python babel_runner.py extract`` to update the ``.pot`` template.
@ -297,13 +325,13 @@ catalogs.
When a new locale is submitted, add a new directory with the ISO 639-1 language When a new locale is submitted, add a new directory with the ISO 639-1 language
identifier and put ``sphinx.po`` in there. Don't forget to update the possible identifier and put ``sphinx.po`` in there. Don't forget to update the possible
values for :confval:`language` in ``doc/usage/configuration.rst``. values for :confval:`language` in :file:`doc/usage/configuration.rst`.
The Sphinx core messages can also be translated on `Transifex The Sphinx core messages can also be translated on `Transifex
<https://www.transifex.com/sphinx-doc/sphinx-1/>`_. There ``tx`` client tool, <https://www.transifex.com/sphinx-doc/sphinx-1/>`_. There ``tx`` client tool,
which is provided by the ``transifex_client`` Python package, can be used to which is provided by the ``transifex_client`` Python package, can be used to
pull translations in ``.po`` format from Transifex. To do this, go to pull translations in ``.po`` format from Transifex. To do this, go to
``sphinx/locale`` and then run ``tx pull -f -l LANG`` where ``LANG`` is an :file:`sphinx/locale` and then run ``tx pull -f -l LANG`` where ``LANG`` is an
existing language identifier. It is good practice to run existing language identifier. It is good practice to run
``python babel_runner.py update`` afterwards to make sure the ``.po`` file has the ``python babel_runner.py update`` afterwards to make sure the ``.po`` file has the
canonical Babel formatting. canonical Babel formatting.
@ -314,9 +342,9 @@ Debugging tips
* Delete the build cache before building documents if you make changes in the * Delete the build cache before building documents if you make changes in the
code by running the command ``make clean`` or using the code by running the command ``make clean`` or using the
:option:`sphinx-build -E` option. :option:`sphinx-build --fresh-env` option.
* Use the :option:`sphinx-build -P` option to run ``pdb`` on exceptions. * Use the :option:`sphinx-build --pdb` option to run ``pdb`` on exceptions.
* Use ``node.pformat()`` and ``node.asdom().toxml()`` to generate a printable * Use ``node.pformat()`` and ``node.asdom().toxml()`` to generate a printable
representation of the document structure. representation of the document structure.
@ -330,17 +358,23 @@ Debugging tips
* Set the debugging options in the `Docutils configuration file * Set the debugging options in the `Docutils configuration file
<https://docutils.sourceforge.io/docs/user/config.html>`_. <https://docutils.sourceforge.io/docs/user/config.html>`_.
* JavaScript stemming algorithms in ``sphinx/search/non-minified-js/*.js``
Updating generated files
------------------------
* JavaScript stemming algorithms in :file:`sphinx/search/non-minified-js/*.js`
are generated using `snowball <https://github.com/snowballstem/snowball>`_ are generated using `snowball <https://github.com/snowballstem/snowball>`_
by cloning the repository, executing ``make dist_libstemmer_js`` and then by cloning the repository, executing ``make dist_libstemmer_js`` and then
unpacking the tarball which is generated in ``dist`` directory. unpacking the tarball which is generated in :file:`dist` directory.
Minified files in ``sphinx/search/minified-js/*.js`` are generated from Minified files in :file:`sphinx/search/minified-js/*.js` are generated from
non-minified ones using ``uglifyjs`` (installed via npm), with ``-m`` non-minified ones using :program:`uglifyjs` (installed via npm), with ``-m``
option to enable mangling. option to enable mangling.
* The ``searchindex.js`` files found in the ``tests/js/fixtures/*`` directories * The :file:`searchindex.js` files found in
are generated by using the standard Sphinx HTML builder on the corresponding the :file:`tests/js/fixtures/*` directories
input projects found in ``tests/js/roots/*``. The fixtures provide test data are generated by using the standard Sphinx HTML builder
used by the Sphinx JavaScript unit tests, and can be regenerated by running on the corresponding input projects found in :file:`tests/js/roots/*`.
the ``utils/generate_js_fixtures.py`` script. The fixtures provide test data used by the Sphinx JavaScript unit tests,
and can be regenerated by running
the :file:`utils/generate_js_fixtures.py` script.