FAQ sphinx¶
Où peut-on trouver la liste des thèmes sphinx ?¶
On a des listes ici:
Quels sont les thèmes les plus employés ?¶
Cela évolue bien sûr au cours du temps ; actuellement (2023-06-02) les thèmes les plus employés sont:
le thème furo pour les petits et moyens projets
le thème pydata-sphinx-theme pour les gros projets scientifiques
le thème sphinx-material come ce site de démonstration
le thème sphinx-book-theme pour les gros projets comme ray par exemple
le récent thème immaterial Exemple : le site recensant les extensions sphinx
Quel est le thème employé sur ce site ?¶
Le thème employé est sphinx_material
Comment créer la page d’index ?¶
La page d’index est créée au moyen des directives sphinx suivantes:
index
glossary
index¶
La directive index s’emploie de différentes manières
avec !¶
.. index::
! Rubrique principale
Avec pair:¶
.. index::
pair: Classe ; ClasseExemple
glossary¶
Cette directive est très puissante puisque tous les termes concernés par glossary se retrouvent dans la page d’index.
Voir la page d’index de ce projet.
Quels sont les documentations sphinx qui peuvent servir d’exemples ?¶
Ces 3 sites recensent les meilleures documentations:
https://github.com/readthedocs-examples/awesome-read-the-docs
https://www.sphinx-doc.org/en/master/examples.html (le site officiel)
On peut citer les projets:
ray (https://docs.ray.io/, récemment (2023-05-31) à la liste https://github.com/readthedocs-examples/awesome-read-the-docs#sphinx-projects
vsketch pour l’utilisation de sphinx-auto-api
voir tuto_sphinx:sphinx_antoine_beyeler_autoapi
le thème utilisé est furo
-
Le thème utilisé est le thème pydata-sphinx-theme
Où peut-on trouver la liste des extensions shinx ?¶
Voici les sites qui recensent les extensions sphinx:
Quel est l’intérêt de literalinclude ?¶
Si on inclut les sources d’un programme, le code est toujours correct.
En particulier, il est très intéressant d’employer :start-after et :end-before:
.. literalinclude:: ../conf.py
:language: bash
:start-after: __begin_intersphinx_mapping__
:end-before: __end_intersphinx_mapping__
Dans ce cas on cible le paramètrage du tableau intersphinx_mapping[]
extensions.append("sphinx.ext.intersphinx")
intersphinx_mapping = {
"tuto_doc": ("https://gdevops.frama.io/documentation/tuto", None),
"doc_news": ("https://gdevops.frama.io/documentation/news", None),
"tuto_sphinx": ("https://gdevops.frama.io/documentation/sphinx/tuto", None),
"tuto_formats": ("https://gdevops.frama.io/documentation/formats", None),
"tuto_python": ("https://gdevops.frama.io/python/tuto", None),
"ray": ("https://docs.ray.io/en/latest/", None),
"sphinx_doc": ("https://www.sphinx-doc.org/en/master/", None),
}
# python -m sphinx.ext.intersphinx http://informatique.gitlab.srv.int.id3.eu/Documentation/objects.inv
# python -m sphinx.ext.intersphinx https://informatique.gitlab.srv.int.id3.eu/intranet/intranet_user/objects.inv
# python -m sphinx.ext.intersphinx https://docs.ray.io/en/latest/objects.inv
# python -m sphinx.ext.intersphinx https://www.sphinx-doc.org/en/master/objects.inv
Important
Il existe aussi les options :start-at et end-at
Comment paramétrer une substitution ?¶
Pour insérer cet avatar aller dans le fichier conf.py et
ajouter cette ligne:
.. |sphinx| image:: /images/sphinx_avatar.png
à rst_prolog:
rst_prolog = """
.. |sphinx| image:: /images/sphinx_avatar.png
.. |myst| image:: /images/myst_avatar.png
.. |id3| image:: /images/id3_avatar.png
"""
Est-ce que la langue est paramètrable ?¶
Au lieu de « Show source » j’ai le bouton « Monter le code source ».
Cela signifie que la variable language est initialisée à « fr ».
Comment enlever le “Show source” à droite ?¶
Il faut initialiser la variable
html_show_sourcelinkdu fichier conf.py à False.