Sphinx prend en charge la modification de l'apparence de sa sortie HTML via des thèmes . Un thème est une collection de modèles HTML, de feuille (s) de style et d’autres fichiers statiques. En outre, il contient un fichier de configuration qui spécifie de quel thème hériter, quel style de surbrillance utiliser et quelles options existent pour personnaliser l'apparence du thème.
Les thèmes sont censés ne pas être conscients des projets, ils peuvent donc être utilisés sans modification pour différents projets.
Utiliser un thème existant est facile. Si le thème est intégré à Sphinx, il vous suffit de définir la valeur de configuration htmltheme . Avec la valeur de configuration htmltheme_options , vous pouvez définir des options spécifiques à un thème qui changent l’apparence. Par exemple, les éléments suivants dans conf.py :
html_theme = "classic"
html_theme_options = {
"rightsidebar" : "true" ,
"relbarbgcolor" : "black"
}
Cela donnerait le thème classique, mais avec une barre latérale à droite et un fond noir pour la barre de relation (la barre avec les liens de navigation en haut et en bas de la page).
Si le thème ne vient pas avec Sphinx, il peut se présenter sous deux formes statiques: soit un répertoire (contenant theme.conf et d’autres fichiers nécessaires), soit un fichier zip contenant le même contenu. L'un ou l'autre doit être placé là où Sphinx peut le trouver; pour cela, il faut utiliser la valeur de configuration html_theme_path. Il donne une liste de répertoires, relatifs au répertoire contenant conf.py, pouvant contenir des répertoires de thèmes ou des fichiers zip. Par exemple, pour utiliser un thème dans le fichier blue.zip, le placer directement dans le répertoire contenant conf.py et utiliser cette configuration:
html_theme = "blue" html_theme_path = [ "." ]
La troisième forme est un paquet python. Si un thème pour utiliser un thème distribué sous forme de package Python:
# installing theme package $ pip install sphinxjp.themes.dotted # use it in your conf.py html_theme = "dotted"
Sphinx est livré avec une sélection de thèmes à choisir.
Il s'agit d'une disposition fondamentalement non stylée utilisée comme base pour les autres thèmes et utilisable comme base pour les thèmes personnalisés. Le HTML contient tous les éléments importants tels que la barre latérale et la barre de relation. Il y a ces options (qui sont héritées par les autres thèmes):
Le thème albatre est un thème «Kr» Sphinx modifié de @kennethreitz (en particulier utilisé dans son projet Requests), lui-même basé à l'origine sur le thème de @mitsuhiko utilisé pour les projets Flask et connexes.
C’est le thème classique, qui ressemble à la documentation de Python 2 . Il peut être personnalisé via ces options:
Le thème utilisé à l'origine par cette documentation. Il comporte une barre latérale sur le côté droit. Il n'y a actuellement aucune option autre que nosidebar et sidebarwidth.
Un thème plus léger, basé sur la documentation de Jinja. Les options de couleur suivantes sont disponibles:
Un thème verdâtre. Il n'y a actuellement aucune option autre que nosidebar et sidebarwidth.
Un thème du projet de framework web Pyramid, conçu par Blaise Laflamme. Il n'y a actuellement aucune option autre nosidebar et sidebarwidth.
Un thème sans barre latérale inspiré du guide de l'utilisateur de Haiku OS. Les options suivantes sont supportées:
Un thème ressemblant à l'ancienne documentation Python. Il n'y a actuellement aucune option autre que nosidebar et sidebarwidth .
Un thème pour le constructeur epub. Ce thème tente de sauver de l’espace visuel qui est une ressource rare sur les lecteurs de livres électroniques. Les options suivantes sont supportées:
Un thème bleuâtre simple. Les options suivantes sont prises en charge au-delà de nosidebar et sidebarwidth :