Builders¶

These are the built-in Sphinx builders. More builders can be added by extensions.

The builder’s « name » must be given to the -M or -b command-line options of sphinx-build to select a builder.

The most common builders are:

html: Build HTML pages. This is the default builder.
dirhtml: Build HTML pages, but with a single directory per document. Makes for prettier URLs (no .html) if served from a webserver.
singlehtml: Build a single HTML with the whole content.
htmlhelp, qthelp, devhelp, epub: Build HTML files with additional information for building a documentation collection in one of these formats.
applehelp: Build an Apple Help Book. Requires hiutil and codesign, which are not Open Source and presently only available on Mac OS X 10.6 and higher.
latex: Build LaTeX sources that can be compiled to a PDF document using pdflatex.
man: Build manual pages in groff format for UNIX systems.
texinfo: Build Texinfo files that can be processed into Info files using makeinfo.
text: Build plain text files.
gettext: Build gettext-style message catalogs (.pot files).
doctest: Run all doctests in the documentation, if the doctest extension is enabled.
linkcheck: Check the integrity of all external links.
xml: Build Docutils-native XML files.
pseudoxml: Build compact pretty-printed « pseudo-XML » files displaying the internal structure of the intermediate document trees.

class sphinx.builders.html.StandaloneHTMLBuilder[source]¶

This is the standard HTML builder. Its output is a directory with HTML files, complete with style sheets and optionally the reStructuredText sources. There are quite a few configuration values that customize the output of this builder, see the chapter Options pour la sortie HTML for details.

name = 'html'¶: The builder’s name. This is the value used to select builders on the command line.

format = 'html'¶: The builder’s output format, or “” if no document output is produced. This is commonly the file extension, e.g. « html », though any string value is accepted. The builder’s format string can be used by various components such as SphinxPostTransform or extensions to determine their compatibility with the builder.

supported_image_types = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']¶: The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

class sphinx.builders.dirhtml.DirectoryHTMLBuilder[source]¶

Il s’agit d’une sous-classe de l’éditeur HTML standard. Son résultat est un répertoire avec des fichiers HTML, où chaque fichier est appelé index.html et placé dans un sous-répertoire nommé comme son nom de page. Par exemple, le document `markup/rest.rst ne donnera pas un fichier de sortie markup/rest.html, mais markup/rest/index.html. Lors de la génération de liens entre les pages, le index.html est omis, afin que l’URL ressemble à markup/rest/.

name = 'dirhtml'¶: The builder’s name. This is the value used to select builders on the command line.

format = 'html'¶: The builder’s output format, or “” if no document output is produced. This is commonly the file extension, e.g. « html », though any string value is accepted. The builder’s format string can be used by various components such as SphinxPostTransform or extensions to determine their compatibility with the builder.

supported_image_types = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']¶: The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Ajouté dans la version 0.6.

class sphinx.builders.singlehtml.SingleFileHTMLBuilder[source]¶

This is an HTML builder that combines the whole project in one output file. (Obviously this only works with smaller projects.) The file is named like the root document. No indices will be generated.

name = 'singlehtml'¶: The builder’s name. This is the value used to select builders on the command line.

format = 'html'¶: The builder’s output format, or “” if no document output is produced. This is commonly the file extension, e.g. « html », though any string value is accepted. The builder’s format string can be used by various components such as SphinxPostTransform or extensions to determine their compatibility with the builder.

supported_image_types = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']¶: The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Ajouté dans la version 1.0.

class sphinxcontrib.htmlhelp.HTMLHelpBuilder[source]¶

Ce constructeur produit le même résultat que le constructeur HTML autonome, mais génère également des fichiers d’aide HTML qui permettent au Microsoft HTML Help Workshop de les compiler dans un fichier CHM.

name = 'htmlhelp'¶: The builder’s name. This is the value used to select builders on the command line.

format = 'html'¶: The builder’s output format, or “” if no document output is produced. This is commonly the file extension, e.g. « html », though any string value is accepted. The builder’s format string can be used by various components such as SphinxPostTransform or extensions to determine their compatibility with the builder.

supported_image_types = ['image/png', 'image/gif', 'image/jpeg']¶: The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

class sphinxcontrib.qthelp.QtHelpBuilder[source]¶

Ce constructeur produit le même résultat que le constructeur HTML autonome, mais génère également des fichiers de support de collection Qt help qui permettent au générateur de collection Qt de les compiler.

Modifié dans la version 2.0: Moved to sphinxcontrib.qthelp from sphinx.builders package.

name = 'qthelp'¶: The builder’s name. This is the value used to select builders on the command line.

format = 'html'¶: The builder’s output format, or “” if no document output is produced. This is commonly the file extension, e.g. « html », though any string value is accepted. The builder’s format string can be used by various components such as SphinxPostTransform or extensions to determine their compatibility with the builder.

supported_image_types = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']¶: The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

class sphinxcontrib.applehelp.AppleHelpBuilder[source]¶

Ce constructeur produit un livre d’aide Apple basé sur le même résultat que le constructeur HTML autonome.

Si le répertoire source contient des dossiers .lproj, celui correspondant à la langue sélectionnée verra son contenu fusionné avec le résultat généré. Ces dossiers seront ignorés par tous les autres types de documentation.

Afin de générer un livre d’aide valide, ce constructeur a besoin de l’outil en ligne de commande hiutil, qui n’est disponible que sous Mac OS X 10.6 et plus. Vous pouvez désactiver l’étape d’indexation en réglant applehelp_disable_external_tools sur True, auquel cas la sortie ne sera valide que lorsque hiutil aura été exécuté sur tous les dossiers .lproj du paquet.

name = 'applehelp'¶: The builder’s name. This is the value used to select builders on the command line.

format = 'html'¶: The builder’s output format, or “” if no document output is produced. This is commonly the file extension, e.g. « html », though any string value is accepted. The builder’s format string can be used by various components such as SphinxPostTransform or extensions to determine their compatibility with the builder.

supported_image_types = ['image/png', 'image/gif', 'image/jpeg', 'image/tiff', 'image/jp2', 'image/svg+xml']¶: The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Ajouté dans la version 1.3.

Modifié dans la version 2.0: Moved to sphinxcontrib.applehelp from sphinx.builders package.

class sphinxcontrib.devhelp.DevhelpBuilder[source]¶

Ce constructeur produit le même résultat que le constructeur HTML autonome, mais génère également GNOME Devhelp fichier de support qui permet au lecteur GNOME Devhelp de les visualiser.

name = 'devhelp'¶: The builder’s name. This is the value used to select builders on the command line.

format = 'html'¶: The builder’s output format, or “” if no document output is produced. This is commonly the file extension, e.g. « html », though any string value is accepted. The builder’s format string can be used by various components such as SphinxPostTransform or extensions to determine their compatibility with the builder.

supported_image_types = ['image/png', 'image/gif', 'image/jpeg']¶: The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Modifié dans la version 2.0: Moved to sphinxcontrib.devhelp from sphinx.builders package.

class sphinx.builders.epub3.Epub3Builder[source]¶

This builder produces the same output as the standalone HTML builder, but also generates an epub file for ebook readers. See Epub info for details about it. For definition of the epub format, have a look at https://idpf.org/epub or https://en.wikipedia.org/wiki/EPUB. The builder creates EPUB 3 files.

name = 'epub'¶: The builder’s name. This is the value used to select builders on the command line.

format = 'html'¶: The builder’s output format, or “” if no document output is produced. This is commonly the file extension, e.g. « html », though any string value is accepted. The builder’s format string can be used by various components such as SphinxPostTransform or extensions to determine their compatibility with the builder.

supported_image_types = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']¶: The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Ajouté dans la version 1.4.

Modifié dans la version 1.5: Since Sphinx 1.5, the epub3 builder is used as the default epub builder.

class sphinx.builders.latex.LaTeXBuilder[source]¶

This builder produces LaTeX source files in the output directory. The actual PDF builds happen inside this output directory and need to be triggered in a second step. This can be done via make all-pdf there. To combine the two steps into only one, use sphinx-build -M (i.e. -M latexpdf not -b latexpdf) or make latexpdf at the project root.

See latex_documents and the chapter Options pour la sortie LaTeX for available options.

PDF builds need a sufficiently complete LaTeX installation. The testing is currently (since 5.3.0) done on Ubuntu 22.04LTS, whose LaTeX distribution matches upstream TeXLive 2021 as of 2022/02/04, but PDF builds can be successfully done on much older LaTeX installations.

At any rate, on Ubuntu for example, following packages must all be present:

texlive-latex-recommended
texlive-fonts-recommended
texlive-fonts-extra (needed for fontawesome5, see the 7.4.0 change notice below)
tex-gyre (if latex_engine left to default)
texlive-latex-extra
latexmk

Modifié dans la version 4.0.0: TeX Gyre fonts now required for 'pdflatex' engine (default).

Modifié dans la version 7.4.0: LaTeX package xcolor is now required (it is part of Ubuntu texlive-latex-recommended anyhow). The LaTeX package fontawesome5 is recommended. See the “sphinxsetup” iconpackage key for more.

Additional packages are needed in some circumstances:

texlive-lang-cyrillic for Cyrillic (and also then cm-super if using the default fonts),
texlive-lang-greek for Greek (and also then cm-super if using the default fonts),
texlive-xetex if latex_engine is 'xelatex',
texlive-luatex if latex_engine is 'lualatex',
fonts-freefont-otf if latex_engine is either 'xelatex' or 'lualatex'.

Note

Since 1.6, make latexpdf uses on GNU/Linux and macOS latexmk, as it makes sure the needed number of runs is automatically executed. On Windows the PDF builds execute a fix number of LaTeX runs (three, then makeindex, then two more).

On peut passer des options à latexmk via la variable LATEXMKOPTS du Makefile. Par exemple :

make latexpdf LATEXMKOPTS="-silent"

réduit la sortie de la console au minimum.

Also, if latexmk is at version 4.52b or higher (January 2017) LATEXMKOPTS="-xelatex" speeds up PDF builds via XeLateX in case of numerous graphics inclusions.

To pass options directly to the (pdf|xe|lua)latex binary, use variable LATEXOPTS, for example:

make latexpdf LATEXOPTS="--halt-on-error"

name = 'latex'¶: The builder’s name. This is the value used to select builders on the command line.

format = 'latex'¶: The builder’s output format, or “” if no document output is produced. This is commonly the file extension, e.g. « html », though any string value is accepted. The builder’s format string can be used by various components such as SphinxPostTransform or extensions to determine their compatibility with the builder.

supported_image_types = ['application/pdf', 'image/png', 'image/jpeg']¶: The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Notez qu’un constructeur PDF direct est fourni par rinohtype. Le nom du constructeur est « rinoh ». Reportez-vous au manuel rinohtype manual pour plus de détails.

class sphinx.builders.text.TextBuilder[source]¶

This builder produces a text file for each reStructuredText file. This is almost the same as the reStructuredText source, but with much of the markup stripped for better readability.

name = 'text'¶: The builder’s name. This is the value used to select builders on the command line.

format = 'text'¶: The builder’s output format, or “” if no document output is produced. This is commonly the file extension, e.g. « html », though any string value is accepted. The builder’s format string can be used by various components such as SphinxPostTransform or extensions to determine their compatibility with the builder.

supported_image_types = []¶: The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Ajouté dans la version 0.4.

class sphinx.builders.manpage.ManualPageBuilder[source]¶

Ce constructeur produit des pages de manuel au format groff. Vous devez spécifier quels documents doivent être inclus dans quelles pages de manuel via la valeur de configuration man_pages.

name = 'man'¶: The builder’s name. This is the value used to select builders on the command line.

format = 'man'¶: The builder’s output format, or “” if no document output is produced. This is commonly the file extension, e.g. « html », though any string value is accepted. The builder’s format string can be used by various components such as SphinxPostTransform or extensions to determine their compatibility with the builder.

supported_image_types = []¶: The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Ajouté dans la version 1.0.

class sphinx.builders.texinfo.TexinfoBuilder[source]¶

Ce constructeur produit des fichiers Texinfo qui peuvent être traités en fichiers Info par le programme makeinfo. Vous devez spécifier quels documents doivent être inclus dans quels fichiers Texinfo via la valeur de configuration texinfo_documents.

Le format Info est la base du système d’aide en ligne utilisé par GNU Emacs et le programme terminal info. Voir Texinfo info pour plus de détails. Le format Texinfo est le système de documentation officiel utilisé par le projet GNU. Plus d’informations sur Texinfo peuvent être trouvées sur https://www.gnu.org/software/texinfo/.

name = 'texinfo'¶: The builder’s name. This is the value used to select builders on the command line.

format = 'texinfo'¶: The builder’s output format, or “” if no document output is produced. This is commonly the file extension, e.g. « html », though any string value is accepted. The builder’s format string can be used by various components such as SphinxPostTransform or extensions to determine their compatibility with the builder.

supported_image_types = ['image/png', 'image/jpeg', 'image/gif']¶: The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Ajouté dans la version 1.1.

class sphinxcontrib.serializinghtml.SerializingHTMLBuilder[source]¶

This builder uses a module that implements the Python serialization API (pickle, simplejson, phpserialize, and others) to dump the generated HTML documentation. The pickle builder is a subclass of it.

Une sous-classe concrète de ce constructeur sérialisant au format PHP serialization pourrait ressembler à ceci:

import phpserialize

class PHPSerializedBuilder(SerializingHTMLBuilder):
    name = 'phpserialized'
    implementation = phpserialize
    out_suffix = '.file.phpdump'
    globalcontext_filename = 'globalcontext.phpdump'
    searchindex_filename = 'searchindex.phpdump'

implementation¶: A module that implements dump(), load(), dumps() and loads() functions that conform to the functions with the same names from the pickle module. Known modules implementing this interface are simplejson, phpserialize, plistlib, and others.

out_suffix¶: Le suffixe pour tous les fichiers réguliers.

globalcontext_filename¶: Le nom du fichier contenant le « contexte globale ». C’est un dictionnaire avec des valeurs générales de configuration telles que le nom du projet.

searchindex_filename¶: Le nom de fichier de l’index de recherche que Sphinx génère.

Voir Détails du constructeur de la sérialisation pour plus de détails sur le format de sortie.

Ajouté dans la version 0.5.

class sphinxcontrib.serializinghtml.PickleHTMLBuilder[source]¶

Ce constructeur produit un répertoire avec des fichiers pickle contenant principalement des fragments HTML et des informations TOC, pour l’utilisation d’une application web (ou outil de post-traitement personnalisé) qui n’utilise pas les modèles HTML standard.

Voir Détails du constructeur de la sérialisation pour plus de détails sur le format de sortie.

name = 'pickle'¶

The builder’s name. This is the value used to select builders on the command line.

L’ancien nom « Web » fonctionne toujours aussi bien.

format = 'html'¶: The builder’s output format, or “” if no document output is produced. This is commonly the file extension, e.g. « html », though any string value is accepted. The builder’s format string can be used by various components such as SphinxPostTransform or extensions to determine their compatibility with the builder.

supported_image_types = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']¶: The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Le suffixe du fichier est .fpickle. Le contexte global s’appelle « globalcontext.pickle », l’index de recherche « searchindex.pickle ».

class sphinxcontrib.serializinghtml.JSONHTMLBuilder[source]¶

Ce constructeur produit un répertoire avec des fichiers JSON contenant principalement des fragments HTML et des informations TOC, pour l’utilisation d’une application web (ou outil de post-traitement personnalisé) qui n’utilise pas les modèles HTML standard.

Voir Détails du constructeur de la sérialisation pour plus de détails sur le format de sortie.

name = 'json'¶: The builder’s name. This is the value used to select builders on the command line.

format = 'html'¶: The builder’s output format, or “” if no document output is produced. This is commonly the file extension, e.g. « html », though any string value is accepted. The builder’s format string can be used by various components such as SphinxPostTransform or extensions to determine their compatibility with the builder.

supported_image_types = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']¶: The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Le suffixe du fichier est .fjson. Le contexte mondial s’appelle « globalcontext.json », l’index de recherche « searchindex.json ».

Ajouté dans la version 0.5.

class sphinx.builders.gettext.MessageCatalogBuilder[source]¶

Ce constructeur produit des catalogues de messages de type gettext. Chaque fichier ou sous-répertoire de niveau supérieur développe un seul modèle de catalogue .pot.

Voir la documentation sur Internationalisation pour plus de détails.

name = 'gettext'¶: The builder’s name. This is the value used to select builders on the command line.

format = ''¶: The builder’s output format, or “” if no document output is produced. This is commonly the file extension, e.g. « html », though any string value is accepted. The builder’s format string can be used by various components such as SphinxPostTransform or extensions to determine their compatibility with the builder.

supported_image_types = []¶: The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Ajouté dans la version 1.1.

class sphinx.builders.changes.ChangesBuilder[source]¶

This builder produces an HTML overview of all versionadded, versionchanged, deprecated and versionremoved directives for the current version. This is useful to generate a changelog file, for example.

name = 'changes'¶: The builder’s name. This is the value used to select builders on the command line.

format = ''¶: The builder’s output format, or “” if no document output is produced. This is commonly the file extension, e.g. « html », though any string value is accepted. The builder’s format string can be used by various components such as SphinxPostTransform or extensions to determine their compatibility with the builder.

supported_image_types = []¶: The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

class sphinx.builders.dummy.DummyBuilder[source]¶

Ce constructeur ne produit aucun rendement. L’entrée est seulement analysée et la cohérence est vérifiée. Ceci est utile pour le la vérification syntaxique.

name = 'dummy'¶: The builder’s name. This is the value used to select builders on the command line.

supported_image_types = []¶: The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Ajouté dans la version 1.4.

class sphinx.builders.linkcheck.CheckExternalLinksBuilder[source]¶

Ce constructeur scanne tous les documents à la recherche de liens externes, essaie de les ouvrir avec des requests, et écrit un aperçu de ceux qui sont cassés et redirigés vers la sortie standard et vers le fichier output.txt dans le répertoire de sortie.

name = 'linkcheck'¶: The builder’s name. This is the value used to select builders on the command line.

format = ''¶: The builder’s output format, or “” if no document output is produced. This is commonly the file extension, e.g. « html », though any string value is accepted. The builder’s format string can be used by various components such as SphinxPostTransform or extensions to determine their compatibility with the builder.

supported_image_types = []¶: The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Modifié dans la version 1.5: Since Sphinx 1.5, the linkcheck builder uses the requests module.

Modifié dans la version 3.4: The linkcheck builder retries links when servers apply rate limits.

class sphinx.builders.xml.XMLBuilder[source]¶

Ce constructeur produit des fichiers XML natifs Docutils. La sortie peut être transformée avec des outils XML standard tels que les processeurs XSLT en formes finales arbitraires.

name = 'xml'¶: The builder’s name. This is the value used to select builders on the command line.

format = 'xml'¶: The builder’s output format, or “” if no document output is produced. This is commonly the file extension, e.g. « html », though any string value is accepted. The builder’s format string can be used by various components such as SphinxPostTransform or extensions to determine their compatibility with the builder.

supported_image_types = []¶: The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Ajouté dans la version 1.2.

class sphinx.builders.xml.PseudoXMLBuilder[source]¶

Ce constructeur est utilisé pour déboguer le pipeline Sphinx/Docutils « Reader to Transform to Writer ». Il produit des fichiers « pseudo-XML » joliment imprimés et compacts, où l’imbrication est indiquée par une indentation (pas de balises de fin). Les attributs externes pour tous les éléments sont édités, et les attributs internes pour les éléments « en attente » restants sont également donnés.

name = 'pseudoxml'¶: The builder’s name. This is the value used to select builders on the command line.

format = 'pseudoxml'¶: The builder’s output format, or “” if no document output is produced. This is commonly the file extension, e.g. « html », though any string value is accepted. The builder’s format string can be used by various components such as SphinxPostTransform or extensions to determine their compatibility with the builder.

supported_image_types = []¶: The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Ajouté dans la version 1.2.

Built-in Sphinx extensions qui offrent plus de constructeurs sont :

Détails du constructeur de la sérialisation¶

All serialization builders outputs one file per source file and a few special files. They also copy the reStructuredText source files to the _sources directory under the output directory.

La classe PickleHTMLBuilder est une sous-classe intégrée qui implémente l’interface de sérialisation pickle.

Les fichiers par fichier source ont les extensions de out_suffix, et sont organisées en répertoires comme les fichiers sources. Ils sont désérialisés en dictionnaire (ou une structure de type dictionnaire) avec ces clés :

body: Le « corps » HTML (c’est-à-dire le rendu HTML du fichier source), tel que rendu par le traducteur HTML.
title: Le titre du document, en HTML (peut contenir des balises).
toc: La table des matières du fichier, rendu en HTML <ul>.
display_toc: Un booléen qui est à « True » si le « toc » contient plus d’une entrée.
current_page_name: Le nom du document du fichier courant.
parents, prev et next: Informations sur les chapitres connexes dans l’arborescence TOC. Chaque relation est un dictionnaire avec les clés « lien » (HREF pour la relation) et « titre » (titre du document associé, en HTML). « parents » est une liste de relations, alors que « précédent » et « suivant » sont une relation unique.
sourcename: Le nom du fichier source sous _sources.

Les fichiers spéciaux se trouvent dans le répertoire de sortie racine. Ils sont :

SerializingHTMLBuilder.globalcontext_filename

Un dictionnaire pickle avec ces clés :

project, copyright, release, version: Les mêmes valeurs que celles données dans le fichier de configuration.
style: html_style.
last_updated: Date de la dernière construction.
builder: Nom du constructeur utilisé, dans le cas de sérialisations, on a toujours la valeur 'pickle'.
titles: Un dictionnaire des titres de tous les documents, sous forme de chaînes HTML.

SerializingHTMLBuilder.searchindex_filename

Un index qui peut être utilisé pour rechercher dans la documentation. C’est une liste sérialisée avec ces entrées :

Une liste de noms de documents indexés.
Une liste de titres de document, sous forme de chaînes HTML, dans le même ordre que la première liste.
Un dictionnaire de correspondance de racines de mot (traité par un stemmer en langue anglaise) à une liste d’entiers, qui sont des indices dans la première liste.

environment.pickle

L’environnement de construction. Il s’agit toujours d’un fichier pickle, indépendant du constructeur et d’une copie de l’environnement utilisé lors du démarrage du constructeur.

Contrairement aux autres fichiers de sérialisation, ce fichier de sérialisation nécessite que le paquet sphinx soit disponible lors de la désérialisation.