python-sphinx Tutoriel
Démarrer avec python-sphinx
Recherche…
Remarques
Cette section fournit une vue d'ensemble de ce qu'est python-sphinx et pourquoi un développeur peut vouloir l'utiliser.
Il devrait également mentionner tous les grands sujets dans python-sphinx, et établir un lien avec les sujets connexes. La documentation de python-sphinx étant nouvelle, vous devrez peut-être créer des versions initiales de ces rubriques connexes.
Installation ou configuration
Comme Sphinx est disponible sur l’ index de package Python , il peut être installé à l’aide de pip :
pip install Sphinx
ou vous pouvez également installer en utilisant easy_install
easy_install -U sphinx
Ensuite, vous pouvez vérifier qu'il a été correctement installé en exécutant la commande suivante:
> sphinx-quickstart --version
Sphinx v1.4.1
Avant de continuer, vous devez suivre certains styles de code pour python PEP 8 . Si vous avez suivi la directive PEP 8 , vous pouvez définir la structure du document dans sphinx et commencer à créer votre documentation .
Démarrage rapide
Pour commencer, allez à la racine du répertoire du projet et lancez:
$ sphinx-quickstart
Vous aurez des options pour créer de la documentation pour votre projet. Pour la configuration par défaut, suivez les commandes ci-dessous:
Prompt Choice
> Root path for the documentation [.]: <ENTER>
> Separate source and build directories (y/N) [n]: y
> Name prefix for templates and static dir [_]: <ENTER>
> Project name: an_example_pypi_project
> Author name(s): Andrew Carter
> Project version: 0.0.1
> Project release [0.0.1]: <ENTER>
> Source file suffix [.rst]: <ENTER>
> Name of your master document (without suffix) [index]: <ENTER>
> autodoc: automatically insert docstrings from modules (y/N) [n]: y
> doctest: automatically test code snippets in doctest blocks (y/N) [n]: n
> intersphinx: link between Sphinx documentation of different projects (y/N) [n]: y
> todo: write “todo” entries that can be shown or hidden on build (y/N) [n]: n
> coverage: checks for documentation coverage (y/N) [n]: n
> pngmath: include math, rendered as PNG images (y/N) [n]: n
> jsmath: include math, rendered in the browser by JSMath (y/N) [n]: n
> ifconfig: conditional inclusion of content based on config values (y/N) [n]: y
> Create Makefile? (Y/n) [y]: n
> Create Windows command file? (Y/n) [y]: n
Après une exécution réussie, vous pouvez découvrir le fichier config.py dans votre répertoire doc / source de votre projet. Ce fichier contrôle la structure de base de la manière dont votre document sera généré lorsque vous exécuterez la commande de construction comme ci-dessous.
$ sphinx-build -b html sourcedir builddir
Les instructions détaillées sont disponibles sur: https://pythonhosted.org/an_example_pypi_project/sphinx.html