Débuter avec python-sphinx

Installation ou configuration

Étant donné que [Sphinx][1] est disponible sur [Python Package Index][2], il peut être installé à l’aide de [pip][3] :

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 un certain style de code pour python [PEP 8][4]. Si vous avez suivi les directives [PEP 8][4], vous pouvez [définir la structure du document][5] dans sphinx et commencer à [construire votre documentation][6].

[1] : http://www.sphinx-doc.org/en/stable/ [2] : https://pypi.python.org/pypi/Sphinx [3] : https://pypi.python.org/pypi/pip [4] : https://www.python.org/dev/peps/pep-0008/ [5] : http://www.sphinx-doc.org/en/stable/tutorial.html#defining-document-structure [6] : http://www.sphinx-doc.org/en/stable/tutorial.html#running-the-build

Démarrage rapide

Pour commencer, allez à la racine du répertoire du projet et exécutez :

$ sphinx-quickstart

Vous obtiendrez 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

Une fois l’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 façon dont votre document sera généré lorsque vous exécuterez la commande de construction comme ci-dessous

$ sphinx-build -b html sourcedir builddir

Des instructions détaillées sont disponibles sur : https://pythonhosted.org/an_example_pypi_project/sphinx.html