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.
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¶

Si vous rencontrez un problème avec Sphinx ou avez une idée pour de nouvelles fonctionnalités, merci de les soumettre à issue tracker sur GitHub ou d’ouvrir une discussion sur la liste de diffusion sphinx-dev .

Pour les rapports de bogues, veuillez inclure la sortie générée pendant le processus de construction, ainsi que le fichier journal créé par Sphinx après avoir rencontré une exception non gérée. L’emplacement de ce fichier doit être indiqué vers la fin du message d’erreur.

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 open 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 email the sphinx-dev mailing list.

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.

Clonez le référentiel forké sur votre machine.

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

Checkout the appropriate branch.

Sphinx adopts Semantic Versioning 2.0.0 (refs: https://semver.org/ ).

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
```
Pour les modifications incompatibles ou importantes nécessitant l’attente de la prochaine version majeure, utilisez la branche master.

For urgent release, a new PATCH branch must be branched from the newest release tag (see Sphinx’s release process for detail).
Installez un environnement virtuel.

This is not necessary for unit testing, thanks to tox, but it is necessary if you wish to run sphinx-build locally or run unit tests without the help of tox:
```
virtualenv ~/.venv
. ~/.venv/bin/activate
pip install -e .
```
Create a new working branch. Choose any name you like.
```
git checkout -b 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 '#42: Add useful new feature that does this.'
```
GitHub recognizes certain phrases that can be used to automatically update the issue tracker. For example:
```
git commit -m 'Closes #42: Fix invalid markup in docstring of Foo.bar.'
```
would close issue #42.
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 respective branch (master or A.x).
Attendez qu’un développeur principal examine vos modifications.

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.
Les nouvelles fonctionnalités doivent être documentées. Inclure des exemples et des cas d’utilisation, le cas échéant. Si possible, incluez un échantillon affiché dans la sortie générée.
Lorsque vous ajoutez une nouvelle variable de configuration, veillez à la documenter et à mettre à jour le fichier :file: sphinx/cmd/quickstart.py si cela est suffisamment important.
Ajouter des tests unitaires appropriés.

Style and type checks can be run as follows:

ruff .
mypy sphinx/

Unit tests¶

Sphinx is tested using pytest for Python code and Karma 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:

Pour lister toutes les cibles possibles
```
tox -av
```
To run unit tests for a specific Python version, such as Python 3.10:
```
tox -e py310
```
To run unit tests for a specific Python version and turn on deprecation warnings so they’re shown in the test output:
```
PYTHONWARNINGS=error tox -e py310
```
Arguments to pytest can be passed via tox, e.g., in order to run a particular test:
```
tox -e py310 tests/test_module.py::test_new_feature
```

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

pip install .[test]

To run JavaScript tests, use npm:

npm install
npm run test

Astuce

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:

FIREFOX_BIN="/Applications/Firefox.app/Contents/MacOS/firefox" npm test

De nouveaux tests unitaires doivent être inclus dans le répertoire tests si nécessaire:

Pour les corrections de bugs, commencez par ajouter un test qui échoue sans vos modifications et réussit après leur application.
Les tests nécessitant une exécution sphinx-build devraient être intégrés si possible à l’un des modules de test existants. Les nouveaux tests portant sur @ with_app, puis sur build_all pour quelques assertions ne sont pas bons, car la suite de tests ne devrait pas prendre plus d’une minute pour s’exécuter.

Added in version 1.8: Sphinx also runs JavaScript tests.

Added in version 1.6: sphinx.testing is added as a experimental.

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

À faire

The below belongs in the developer guide

Utility functions and pytest fixtures for testing are provided in sphinx.testing. If you are a developer of Sphinx extensions, you can write unit tests by using pytest. At this time, sphinx.testing will help your test implementation.

How to use pytest fixtures that are provided by sphinx.testing? You can require 'sphinx.testing.fixtures' in your test modules or conftest.py files like this:

pytest_plugins = 'sphinx.testing.fixtures'

If you want to know more detailed usage, please refer to tests/conftest.py and other test_*.py files under the tests directory.

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.

À faire

Add a more extensive documentation contribution guide.

Build the documentation¶

To build the documentation, run the following command:

sphinx-build -M html ./doc ./build/sphinx -W --keep-going

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, 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.

Sphinx uses Babel to extract messages and maintain the catalog files. The utils directory contains a helper script, 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 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 values for language in doc/usage/configuration.rst.

The Sphinx core messages can also be translated on Transifex. There tx client tool, 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 sphinx/locale and then run tx pull -f -l LANG where LANG is an existing language identifier. It is good practice to run python babel_runner.py update afterwards to make sure the .po file has the canonical Babel formatting.

Debugging tips¶

Supprimez le cache de construction avant de créer des documents si vous apportez des modifications dans le code en exécutant la commande make clean ou en utilisant l’option sphinx-build -E.
Utilisez l’option :option: sphinx-build -P pour exécuter pdb sur les 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 :confval: nitpicky sur True afin que Sphinx indique les références sans cible connue.
Set the debugging options in the Docutils configuration file.
JavaScript stemming algorithms in sphinx/search/non-minified-js/*.js are generated using snowball by cloning the repository, executing make dist_libstemmer_js and then unpacking the tarball which is generated in dist directory.

Minified files in sphinx/search/minified-js/*.js are generated from non-minified ones using uglifyjs (installed via npm), with -m option to enable mangling.

Sphinx

On this page

Site navigation