Sphinx 7.3.0 (2024-04-17)

Dependencies

Features added

Support theme configuration via theme.toml files

theme.conf and INI-styled theme configuration has served Sphinx well for several years.

However, the format suffers from under-specification and a lack of support for anything more than simple key-value pairs. This has led in recent history to adding support for lists of stylesheets or sidebar templates delimited by commas, which is not the most straightforwards.

This series of commits adds first-class support for theme configuration via theme.toml files, which are TOML-formatted documents.

theme.conf files remain supported.

At some point in the future we may discuss deprecating support, but that seems some way off for now.

We also include an automatic conversion tool via python -m sphinx.theming conf_to_toml [THEME DIRECTORY], which writes a new theme.toml file to disk without modifying the existing theme.conf file.

HTML Search: Adopt the new <search> element

There’s also a new <search> element: https://webkit.org/blog/14445/webkit-features-in-safari-17-0/

Add long option names to sphinx-build (Improve usability of sphinx-build)

Detail

I find it very difficult to remember what the single letter command-line arguments are for sphinx-build and often have to re-look them up via –help

I usually use sphinx-build via a Makfile, and long options are just fine there, and better at self-documenting

Long options are a CLI best practice, see Command Line Interface Guidelines

Have full-length versions of all flags. For example, have both -h and –help.

Having the full version is useful in scripts where you want to be verbose and descriptive, and you don’t have to look up the meaning of flags everywhere.

And GNU Coding Standards:

Please define long-named options that are equivalent to the single-letter Unix-style options. We hope to make GNU more user friendly this way.

sphinx-build –help before 7.3.0 

positional arguments:
  sourcedir         chemin des fichiers sources de la documentation
  outputdir         chemin du répertoire de sortie
  filenames         une liste de fichiers spécifiques à reconstruire. Sera ignoré si l'option -a est spécifiée.

options:
  -h, --help        show this help message and exit
  --version         show program's version number and exit

options générales:
  -b BUILDER        constructeur à utiliser (par defaut: HTML)
  -a                enregistrer tous les fichiers (par défaut : enregistrer seulement les fichiers nouveaux ou modifiés)
  -E                ne pas utiliser un environnement sauvegardé, relire toujours tous les fichiers
  -d PATH           chemin pour le cache d'environnement et de fichiers doctree (défaut : OUTPUTDIR/.doctrees)
  -j N, --jobs N    build parallèle avec N processus si possible (la valeur spéciale "auto" ajuste N à cpu-count)

build configuration options:
  -c PATH           chemin dans lequel se trouve le fichier de configuration (conf.py). (valeur par défaut : identique à SOURCEDIR).
  -C                n'utilisez aucun fichier de configuration, seulement l'option -D
  -D setting=value  outre passer un paramètre du fichier de configuration
  -A name=value     passer une valeur aux templates HTML
  -t TAG            définit une balise : seules les blocs "only" avec TAG seront inclus
  -n                mode sourcilleux, signale toute référence manquante

options de la console de sortie:
  -v                augmenter la verbosité (peut être répété)
  -q                aucune sortie vers stdout, seulement les avertissements vers stderr
  -Q                aucune sortie du tout, même pas les avertissements
  --color           émettre une sortie de couleur (par défaut : auto-détection)
  -N, --no-color    ne pas émettre une sortie de couleur (par défaut : auto-détection)
  -w FILE           écrire les avertissements (et les erreurs) vers le fichier spécifié
  -W                modifier les avertissements en erreurs
  --keep-going      avec -W, l'exécution se poursuit en cas d'avertissements
  -T                montrer la trace d’appels complète si une exception est levée
  -P                exécuter Pdb si une exception se produit.

Pour plus d'informations, visitez le site <https://www.sphinx-doc.org/>.

sphinx-build –help after 7.3.0 

positional arguments:
  SOURCE_DIR            chemin des fichiers sources de la documentation
  OUTPUT_DIR            chemin du répertoire de sortie
  filenames             (optional) a list of specific files to rebuild. Ignored if --write-all is specified

options:
  -h, --help            show this help message and exit
  --version             show program's version number and exit

options générales:
  --builder BUILDER, -b BUILDER
                        constructeur à utiliser (par défaut: 'html')
  --jobs N, -j N        run in parallel with N processes, when possible. 'auto' uses the number of CPU cores
  --write-all, -a       enregistrer tous les fichiers (par défaut : enregistrer seulement les fichiers nouveaux ou modifiés)
  --fresh-env, -E       ne pas utiliser un environnement sauvegardé, relire toujours tous les fichiers

path options:
  --doctree-dir PATH, -d PATH
                        directory for doctree and environment files (default: OUTPUT_DIR/.doctrees)
  --conf-dir PATH, -c PATH
                        directory for the configuration file (conf.py) (default: SOURCE_DIR)

build configuration options:
  --isolated, -C        use no configuration file, only use settings from -D options
  --define setting=value, -D setting=value
                        outre passer un paramètre du fichier de configuration
  --html-define name=value, -A name=value
                        passer une valeur aux templates HTML
  --tag TAG, -t TAG     définit une balise : seules les blocs "only" avec TAG seront inclus
  --nitpicky, -n        nit-picky mode: warn about all missing references

options de la console de sortie:
  --verbose, -v         augmenter la verbosité (peut être répété)
  --quiet, -q           aucune sortie vers stdout, seulement les avertissements vers stderr
  --silent, -Q          aucune sortie du tout, même pas les avertissements
  --color               émettre une sortie de couleur (par défaut : auto-détection)
  --no-color, -N        ne pas émettre une sortie de couleur (par défaut : auto-détection)

warning control options:
  --warning-file FILE, -w FILE
                        écrire les avertissements (et les erreurs) vers le fichier spécifié
  --fail-on-warning, -W
                        modifier les avertissements en erreurs
  --keep-going          with --fail-on-warning, keep going when getting warnings
  --show-traceback, -T  montrer la trace d’appels complète si une exception est levée
  --pdb, -P             exécuter Pdb si une exception se produit.

Pour plus d'informations, visitez le site <https://www.sphinx-doc.org/>.

Add a versionremoved directive

Supprimé dans la version version: Similar to versionadded, but describes when the feature was removed. An explanation may be provided to inform the reader what to use instead, or why the feature was removed. Example:

Supprimé dans la version 4.0: The spam() function is more flexible, and should be used instead.

Change the text of the versionadded directive from New in […] to Added in […]

  • #11015: Change the text of the versionadded directive from New in […] to Added in […]. Patch by Bénédikt Tran.

Added show_warning_types configuration option

If True, the type of each warning is added as a suffix to the warning message, e.g., WARNING: […] [index] or WARNING: […] [toc.circular].

The default is False.

Added in version 7.3.0..

Other

  • #11855: Defer computation of configuration values. Patch by Adam Turner.

  • Add :no-search: as an alias of the :nosearch: metadata field. Patch by Adam Turner.

  • #11803: autodoc: Use an overriden __repr__() function in an enum, if defined. Patch by Shengyu Zhang.

  • #11825: Allow custom targets in the manpage role. Patch by Nicolas Peugnet.

  • #11892: Improved performance when resolving cross references in the C++ domain. Patch by Rouslan Korneychuk.

  • #11981: Improve rendering of signatures using slice syntax, e.g., def foo(arg: np.float64[:,:]) -> None: ….

  • The manpage builder now adds OSC 8 anchors to hyperlinks, using the groff device control command.

  • #12193: Improve external warnings for unknown roles. In particular, suggest related role names if an object type is mistakenly used. Patch by Chris Sewell.

  • Add public type alias sphinx.util.typing.ExtensionMetadata. This can be used by extension developers to annotate the return type of their setup function. Patch by Chris Sewell.