Contribuer à Sphinx¶

There are many ways you can contribute to Sphinx, be it filing bug reports or feature requests, writing new documentation or submitting patches for new or fixed behavior. This guide serves to illustrate how you can get started with this.

Get help¶

The Sphinx community maintains a number of mailing lists and IRC channels.

Stack Overflow with tag python-sphinx: Questions and answers about use and development.
GitHub Discussions Q&A: Question-and-answer style forum for discussions.
sphinx-users <sphinx-users@googlegroups.com>: Liste de diffusion pour le support utilisateur.
sphinx-dev <sphinx-dev@googlegroups.com>: Liste de diffusion pour les discussions relatives au développement.
#sphinx-doc on irc.libera.chat: canal IRC pour les question relatives au développement et au support utilisateur.

Rapport de Bug et demandes de fonstionnalités¶

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.

For bug reports, please include the output produced during the build process 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 error message. Please also include the output of sphinx-build --bug-report.

Inclure ou fournir un lien vers les fichiers source impliqués peut nous aider à résoudre le problème. Si possible, essayez de créer un projet minimal qui génère l’erreur et publiez-le à la place.

Contribute code¶

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 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 before it is merged into the main repository.

Démarrer avec Sphinx¶

Before starting on a patch, we recommend checking for open issues or opening a fresh issue to start a discussion around a feature idea or a bug. If you feel uncomfortable or uncertain about an issue or your changes, feel free to start a discussion.

Ce sont les étapes de base nécessaires pour commencer à développer sur Sphinx.

Créer un compte sur GitHub.
Fork the main Sphinx repository (sphinx-doc/sphinx) using the GitHub interface.

Clone the forked repository to your machine.

git clone https://github.com/<USERNAME>/sphinx
cd sphinx

Install uv and set up your environment.

We recommend using uv for dependency management. Install it with:
```
python -m pip install -U uv
```
Then, set up your environment:
```
uv sync
```
Alternative: If you prefer not to use uv, you can use pip:
```
python -m venv .venv
. .venv/bin/activate
python -m pip install -e .
```
Create a new working branch. Choose any name you like.
```
git switch -c feature-xyz
```
Hack, hack, hack.

Write your code along with tests that shows that the bug was fixed or that the feature works as expected.
Add a bullet point to CHANGES.rst if the fix or feature is not trivial (small doc updates, typo fixes), then commit:
```
git commit -m 'Add useful new feature that does this.'
```
Push changes in the branch to your forked repository on GitHub:
```
git push origin feature-xyz
```
Submit a pull request from your branch to the master branch.

GitHub recognizes certain phrases that can be used to automatically update the issue tracker. For example, including “Closes #42” in the body of your pull request will close issue #42 if the PR is merged.
Wait for a core developer or contributor to review your changes.

You may be asked to address comments on the review. If so, please avoid force pushing to the branch. Sphinx uses the squash merge strategy when merging PRs, so follow-up commits will all be combined.

Coding style¶

Please follow these guidelines when writing code for Sphinx:

Try to use the same code style as used in the rest of the project.
For non-trivial changes, please update the CHANGES.rst file. If your changes alter existing behavior, please document this.
New features should be documented. Include examples and use cases where appropriate. 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 sphinx/cmd/quickstart.py if it’s important enough.
Ajouter des tests unitaires appropriés.

Style and type checks can be run as follows:

uv run ruff check
uv run ruff format
uv run mypy

Unit tests¶

Sphinx is tested using pytest for Python code and Jasmine for JavaScript.

To run Python unit tests, we recommend using tox, which provides a number of targets and allows testing against multiple different Python environments:

To list all possible targets:
```
tox -av
```
To run unit tests for a specific Python version, such as Python 3.14:
```
tox -e py314
```
Arguments to pytest can be passed via tox, e.g., in order to run a particular test:
```
tox -e py314 tests/test_module.py::test_new_feature
```

You can also test by installing dependencies in your local environment:

uv run pytest

Or with pip:

python -m pip install . --group test
pytest

To run JavaScript tests, use npm:

npm install
npm run test

Astuce

jasmine requires a Firefox binary to use as a test browser.

On Unix systems, you can check the presence and location of the firefox binary at the command-line by running command -v firefox.

New unit tests should be included in the tests/ directory where necessary:

Pour les corrections de bugs, commencez par ajouter un test qui échoue sans vos modifications et réussit après leur application.
Tests that need a sphinx-build run should be integrated in one of the existing test modules if possible.
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.

Ajouté dans la version 1.8: Sphinx also runs JavaScript tests.

Modifié dans la version 1.5.2: Sphinx was switched from nose to pytest.

Contribute documentation¶

Contributing to documentation involves modifying the source files found in the doc/ folder. To get started, you should first follow Démarrer avec Sphinx, and then take the steps below to work with the documentation.

The following sections describe how to get started with contributing documentation, as well as key aspects of a few different tools that we use.

Build the documentation¶

To build the documentation, run the following command:

sphinx-build -M html ./doc ./build/sphinx --fail-on-warning

This will parse the Sphinx documentation’s source files and generate HTML for you to preview in build/sphinx/html.

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 edits. To do so, use sphinx-autobuild to run the following command:

sphinx-autobuild ./doc ./build/sphinx/

Traductions¶

The parts of messages in Sphinx that go into builds are translated into several locales. The translations are kept as gettext .po files translated from the master template sphinx/locale/sphinx.pot.

These Sphinx core messages are translated using the online Transifex platform.

Translated strings from the platform are pulled into the Sphinx repository by a maintainer before a new release.

We do not accept pull requests altering the translation files directly. Instead, please contribute translations via the Transifex platform.

Translations notes for maintainers¶

The transifex CLI (tx) can be used 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 existing language identifier. It is good practice to run python utils/babel_runner.py update afterwards to make sure the .po file has the canonical Babel formatting.

Sphinx uses Babel to extract messages and maintain the catalog files. The utils directory contains a helper script, utils/babel_runner.py.

Use python babel_runner.py extract to update the .pot template.
Use python babel_runner.py update to update all existing language catalogs in sphinx/locale/*/LC_MESSAGES with the current messages in the template file.
Use python babel_runner.py compile to compile the .po files to binary .mo files and .js files.

When an updated .po file is submitted, run python babel_runner.py compile to commit both the source and the compiled catalogs.

When a new locale is added, add a new directory with the ISO 639-1 language identifier and put sphinx.po in there. Don’t forget to update the possible values for language in doc/usage/configuration.rst.

Debugging tips¶

Delete the build cache before building documents if you make changes in the code by running the command make clean or using the sphinx-build --fresh-env option.
Use the sphinx-build --pdb option to run pdb on exceptions.
Utilisez node.pformat () et node.asdom ().Toxml () pour générer une représentation imprimable de la structure du document.
Définissez la variable de configuration keep_warnings sur True afin que les avertissements soient affichés dans la sortie générée.
Définissez la variable de configuration nitpicky sur True afin que Sphinx indique les références sans cible connue.
Set the debugging options in the Docutils configuration file.

Updating generated files¶

JavaScript stemming algorithms in sphinx/search/non-minified-js/*.js and stopword files in sphinx/search/_stopwords/ are generated from the Snowball project by running utils/generate_snowball.py.

Minified files in sphinx/search/minified-js/*.js are generated from non-minified ones using uglifyjs (installed via npm). See sphinx/search/minified-js/README.rst.
The searchindex.js files found in the tests/js/fixtures/* directories are generated by using the standard Sphinx HTML builder on the corresponding input projects found in tests/js/roots/*. The fixtures provide test data used by the Sphinx JavaScript unit tests, and can be regenerated by running the utils/generate_js_fixtures.py script.