Créer une documentation de projet Python dans Sphinx

Sphinx est devenu un outil majeur pour écrire de la documentation dans des projets Python, comme Sphinx. Par conséquent, nous allons expliquer ici la procédure de création d'un document de projet Python dans Sphinx.

Installation du Sphinx

Sphinx est expliqué en détail sur le site Web de l'Association des utilisateurs japonais. Bien entendu, la procédure d'installation est également incluse.

Sphinx-Users.jp

Dans l'explication ci-dessus, ʻeasy_install est utilisé, mais si vous utilisez pip install Sphinxou Anaconda / Miniconda, vous pouvez également l'installer avecconda install Sphinx`.

Depuis le 2 août 2015, la dernière version 2.0 de Babel dont dépend Sphinx a [il y a un problème] dans l'environnement Python3 (https://github.com/mitsuhiko/babel/issues/174). Pour contourner ce problème, exécutez pip uninstall babel puis rétrogradez avec pip install babel == 1.3, mais installez directement depuis la branche sur GitHub ( pip install git + https: // github.com / mitsuhiko / babel.git @ 2.0).

Puisque Sphinx est un outil qui est utilisé en commun par les projets, je pense qu'il est préférable de l'installer globalement, pas dans un environnement virtuel tel que virtualenv.

Si elle est installée dans un environnement virtuel, la bibliothèque dépendante du projet lui-même et la bibliothèque dépendante de Sphinx juste pour créer des documents seront mélangées, et requirements.txt sera redondant.

création de documents

À partir de là, nous allons créer le document. Je pense qu'il est plus facile d'obtenir une image s'il y a un exemple concret, j'ai donc préparé un exemple de référentiel ci-dessous. Je pense qu'il est plus facile de comprendre si vous vous référez ici pour la structure des dossiers et les parties modifiées de la source.

icoxfog417/python_doc_sample

Tout d'abord, créez un dossier appelé docs directement sous le projet Python et créez-y des documents. Allez dans le dossier docs que vous avez créé et exécutez sphinx-quickstart pour créer un modèle.

sphinx-quickstart

Pour plus de détails sur cette commande, reportez-vous à «Explication détaillée de sphinx-quickstart» sur cette page.

Le document est maintenant prêt. Cependant, quelque chose comme une référence API veut naturellement être généré automatiquement à partir du code source. Dans Sphinx, vous pouvez utiliser sphinx-apidoc pour générer des documents à partir de ce code source. La commande suivante génère le document du package Python python_doc_sample dans ʻapis dans le dossier docs` (la commande est exécutée à partir de la racine du projet).

sphinx-apidoc -f -o docs/apis python_doc_sample

Notez que selon la méthode d'importation, même le document importé sera créé sous la forme d'une pomme de terre (voir ici](http://shouhei.github.io/blog/2014/12/29/shpinxdeapifalsedokiyumentosheng-cheng-wosurushi) -falsezhu-yi-dian /)).

Vous disposez maintenant de la documentation et de la référence API de votre projet. Dans les deux cas, le document est écrit au format reStructuredText avec l'extension .rst. Finalement, vous devez le convertir au format HTML. La commande pour cela est sphinx-build, mais elle est plus facile à utiliser make (même sous Windows, elle est disponible parce que make.bat est créé lorsque vous exécutez sphinx-quickstart).

make html

Et, éditez conf.py avant d'exécuter la commande (il devrait être directement sous le dossier docs). En effet, la documentation automatique à partir du code Python n'est pas activée par défaut.

`conf.py`


...
sys.path.insert(0, os.path.abspath('../')) 

...
extensions = ["sphinx.ext.autodoc"]

Dans sys.path.insert autour de la 23ème ligne, placez le chemin vers le package Python créé.
Ajoutez l'extension sphinx.ext.autodoc pour créer la documentation de l'API dans ʻextensions` autour de la ligne 33.

Si vous exécutez make html après avoir modifié conf.py, un fichier HTML sera créé dans le dossier _build, et vous pouvez vous référer à la page Web suivante.

Et à partir du lien Index du module, vous pouvez rechercher / référencer la documentation API créée à partir des packages de votre projet.

Si vous écrivez correctement les commentaires, cela ressemblera à ce qui suit.

Après cela, après la mise à jour du document (.rst), la page HTML sera mise à jour avec make html. Cependant, si vous souhaitez modifier le code source, vous devez exécuter sphinx-apidoc, et si cela vous pose problème, vous pouvez créer un simple batch ou script ([Sample](https: // github.). com / icoxfog417 / python_doc_sample / blob / master / make_docs.py)).

Les commandes présentées ci-dessus sont référencées ci-dessous, veuillez donc vous y référer lorsque vous vérifiez la signification des options.

Sphinx Documentation

Publication de la documentation

Le document créé étant une page HTML, vous pouvez facilement le publier sur le serveur. Pour les référentiels GitHub, vous pouvez utiliser des pages GitHub.

Creating Project Pages manually

Poussez le dossier _build où la page HTML est créée vers gh-pages et la publication est terminée. Cependant, veuillez noter que vous avez besoin d'un fichier .nojekyll pour accéder aux fichiers statiques.

Vous pouvez maintenant créer et publier la documentation de votre projet Python dans Sphinx!