# SPHINX: Prise en charge des thèmes HTML

{{INLINETOC}}

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

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 html_theme . Avec la valeur de configuration html_theme_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"

# Thèmes intégrés

Sphinx est livré avec une sélection de thèmes à choisir.

## basic
  

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):

  * **nosidebar (true ou false)**: ne pas inclure la barre latérale. La valeur par défaut est False.
  * **sidebarwidth (int ou str)**: largeur de la barre latérale en pixels. Cela peut être un int, qui est interprété en pixels ou une chaîne de dimension CSS valide telle que '70em' ou '50%'. La valeur par défaut est 230 pixels.
  * **body\_min\_width (int ou str)**: largeur minimale du corps du document. Cela peut être un int, qui est interprété en pixels ou une chaîne de dimension CSS valide telle que '70em' ou '50% '. Utiliser 0 pour ne pas limiter la largeur. Les valeurs par défaut peuvent dépendre du thème (souvent 450 pixels).
  * **body\_max\_width (int ou str)**: largeur maximale du corps du document. Cela peut être un int, qui est interprété en pixels ou une chaîne de dimension CSS valide telle que '70em' ou '50% '. Utiliser 'none' si vous ne voulez pas de limite de largeur. Les valeurs par défaut peuvent dépendre du thème (souvent 800 pixels). 


## albatre

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. 

##classic

C’est le thème classique, qui ressemble à la documentation de Python 2 . Il peut être personnalisé via ces options:
    * **rightidebar (true ou false)**: place la barre latérale à droite. La valeur par défaut est False .
    * **stickysidebar (true ou false)**: Modifie la barre latérale pour qu'elle ne défile pas de manière cachée lorsque le contenu du corps est long. Cela peut ne pas fonctionner avec tous les navigateurs. La valeur par défaut est False .
    * **collapsiblesidebar (true ou false)**: ajoute un fragment de code JavaScript expérimental permettant de réduire la barre latérale au moyen d’un bouton situé sur le côté. La valeur par défaut est False .
    * **externalrefs (true ou false)**: affiche les liens externes différemment des liens internes. La valeur par défaut est False . 
    * Il existe également diverses options de couleur et de police pouvant modifier le jeu de couleurs sans avoir à écrire une feuille de style personnalisée:
      * **footerbgcolor (couleur CSS)**: couleur d'arrière-plan de la ligne de pied de page.
      * **footertextcolor (CSS CSS)**: couleur du texte pour la ligne de pied de page.
      * **sidebarbgcolor (couleur CSS)**: couleur d'arrière-plan de la barre latérale.
      * **sidebarbtncolor (couleur CSS)**: couleur d'arrière-plan du bouton de réduction de la barre latérale (utilisé lorsque collapsiblesidebar a la valeur True ).
      * **sidebartextcolor (couleur CSS)**: couleur du texte de la barre latérale.
      * **sidebarlinkcolor (couleur CSS)**: Couleur du lien pour la barre latérale.
      * **relbarbgcolor (couleur CSS)**: couleur d'arrière-plan de la barre de relation.
      * **relbartextcolor (couleur CSS)**: couleur du texte pour la barre de relation.
      * **relbarlinkcolor (couleur CSS)**: couleur du lien pour la barre de relation.
      * **bgcolor (couleur CSS)**: couleur de fond du corps.
      * **textcolor (couleur CSS)**: couleur du corps du texte.
      * **linkcolor (couleur CSS)**: couleur du lien du corps.
      * **visitedlinkcolor (couleur CSS)**: couleur du corps des liens visités.
      * **headbgcolor (couleur CSS)**: couleur de fond des en-têtes.
      * **headtextcolor (CSS CSS)**: couleur du texte pour les en-têtes.
      * **headlinkcolor (couleur CSS)**: Couleur du lien pour les en-têtes.
      * **codebgcolor (couleur CSS)**: couleur d'arrière-plan des blocs de code.
      * **codetextcolor (couleur CSS)**: couleur de texte par défaut pour les blocs de code, si elle n'est pas définie différemment par le style de surbrillance.
      * **bodyfont (famille de polices CSS)**: police pour le texte normal.
      * **headfont (famille de polices CSS)**: police pour les en-têtes. 

## sphinxdoc

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

## scrolls

Un thème plus léger, basé sur la documentation de Jinja. Les options de couleur suivantes sont disponibles:
    * **headerbordercolor**
    * **subheadlinecolor**
    * **linkcolor**
    * **visitedlinkcolor**
    * **admonitioncolor**
  * **agogo** - Un thème créé par Andi Albrecht. Les options suivantes sont supportées:
    * **bodyfont (famille de polices CSS)**: police pour le texte normal.
    * **headerfont (famille de polices CSS)**: police pour les en-têtes.
    * **pagewidth (longueur CSS)**: largeur du contenu de la page, 70em par défaut.
    * **documentwidth (longueur CSS)**: largeur du document (sans barre latérale), 50em par défaut.
    * **sidebarwidth (longueur CSS)**: largeur de la barre latérale, 20em par défaut.
    * **bgcolor (couleur CSS)**: couleur de fond.
    * **headerbg (valeur CSS pour «background»)**: arrière-plan pour la zone d'en-tête, par défaut un dégradé grisâtre.
    * **footerbg (valeur CSS pour «background»)**: arrière-plan pour la zone de pied de page, par défaut un dégradé gris clair.
    * **linkcolor (couleur CSS)**: couleur du lien du corps.
    * **headercolor1 , headercolor2 (couleur CSS)**: couleurs des en-têtes <h1> et <h2>.
    * **headerlinkcolor (couleur CSS)**: couleur du lien de backreference dans les en-têtes.
    * **textalign (CSS text-align value)**: alignement du texte pour le corps, valeur par défaut justify . 

## nature

Un thème verdâtre. Il n'y a actuellement aucune option autre que **nosidebar** et **sidebarwidth**.

## pyramid

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

## haiku

Un thème sans barre latérale inspiré du guide de l'utilisateur de Haiku OS. Les options suivantes sont supportées:
    * **full\_logo (true ou false, False par défaut)**: si cela est vrai, l'en-tête ne montrera que le html_logo . Utilisez ceci pour les gros logos. Si cela est faux, le logo (si présent) sera affiché comme flottant à droite et le titre de la documentation sera placé dans l'en-tête.
    * **textcolor , headingcolor , linkcolor , visitedlinkcolor , hoverlinkcolor (couleurs CSS)**: couleurs de divers éléments du corps. 

## traditional

Un thème ressemblant à l'ancienne documentation Python. Il n'y a actuellement aucune option autre que nosidebar et sidebarwidth .

## epub

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:
  * **relbar1 (true ou false, True par défaut)**: si cela est vrai, le bloc relbar1 est inséré dans la sortie epub, sinon il est omis.
  * **footer (true ou false, True par défaut)**: si cela est vrai, le bloc de pied de page est inséré dans la sortie epub, sinon il est omis. 

## bizstyle

Un thème bleuâtre simple. Les options suivantes sont prises en charge au-delà de nosidebar et sidebarwidth :
  *  **rightidebar (true ou false)**: place la barre latérale à droite. La valeur par défaut est False .