J'ai [publié] une meilleure pratique que ci-dessous (http://qiita.com/koreyou/items/00f5820591ec9196ef07). Je pense que la pratique dans ce post est également valable en fonction des conditions, je vais donc la laisser pour l'instant.
sphinx-apidoc est un puissant outil d'automatisation de création de documentation API. Il existe un outil d'intégration sphinx dans setuptools, mais pour utiliser sphinx-apidoc, il est nécessaire d'exécuter sphinx-apidoc une fois avec CLI, puis de construire sphinx avec setuptools, etc. L'automatisation n'est pas bonne //github.com/sphinx-doc/sphinx/issues/1135). Cet article décrit comment exécuter à la fois sphinx-apidoc et sphinx en une seule commande.
En passant, je ne suis pas impliqué dans le développement d'OSS, donc je ne suis pas sûr que ce qui suit soit une bonne pratique.
Installez Sphinx et créez un répertoire de documentation.
$ pip install sphinx
$ sphinx-quickstart
Suivez le guide de démarrage rapide pour répondre correctement aux questions. Vous trouverez ci-dessous une liste des seules questions auxquelles il faut répondre pour adopter cette approche.
Welcome to the Sphinx 1.6.1 quickstart utility.
Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).
Enter the root path for documentation.
> Root path for the documentation [.]: doc
You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: y
...
Please indicate if you want to use one of the following Sphinx extensions:
> autodoc: automatically insert docstrings from modules (y/n) [n]: y
Ensuite, un répertoire doc / avec la structure suivante sera créé sous le répertoire.
.
├── doc/
│ ├── build/
│ └── source/
│ ├── _build/
│ ├── conf.py
│ ├── index.rst
│ ├── _static/
│ └── _templates/
├── README.md
├── setup.cfg
├── setup.py
├── test/
├── my_project/
Écrivez setup.py comme suit. Lorsque vous n'utilisez que sphinx, écrivez uniquement setup (cmd class = {'build_sphinx': BuildDoc}, ...), mais cette fois a hérité de BuildDoc et ajouté ʻapidoc` comme prétraitement. Définissez une nouvelle commande.
setup.py
import os
from setuptools import setup
from setuptools.extension import Extension
import sphinx.apidoc
from sphinx.setup_command import BuildDoc
class BuildDocApiDoc(BuildDoc, object):
# inherit from object to enable 'super'
user_options = []
description = 'sphinx'
def run(self):
# metadata contains information supplied in setup()
metadata = self.distribution.metadata
# package_dir may be None, in that case use the current directory.
src_dir = (self.distribution.package_dir or {'': ''})['']
src_dir = os.path.join(os.getcwd(), src_dir)
# Run sphinx by calling the main method, '--full' also adds a conf.py
sphinx.apidoc.main(
['', '-f', '-H', metadata.name, '-A', metadata.author,
'-V', metadata.version, '-R', metadata.version, '-T',
'-o', os.path.join('doc', 'source', 'modules'), src_dir])
super(BuildDocApiDoc, self).run()
name = 'my_project'
version = '0.1'
release = '0.1.0'
setup(
name=name,
author='koreyou',
version=version,
packages=['my_project', ],
license='Creative Commons BY',
cmdclass = {'build_sphinx': BuildDocApiDoc},
command_options={
'build_sphinx': {
'project': ('setup.py', name),
'version': ('setup.py', version),
'release': ('setup.py', release)}},
setup_requires = ['sphinx'],
)
De plus, réécrivez certains fichiers.
setup.cfg
[build_sphinx]
source-dir = doc/source
build-dir = doc/build
all_files = 1
doc/source/conf.py
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../..'))
doc/source/index.rst
.. toctree::
- :maxdepth: 2
- :caption: Contents:
+ :glob:
+ :caption: Modules
+ :maxdepth: 4
+ modules/*
python setup.up build_sphinx
Une fois que diverses informations ont été transmises, si elles se terminent normalement, le document API doit être créé sous doc / build / html / index.html.
De plus, en ce qui concerne la gestion des versions, doc / source / modules est généré automatiquement, alors entrez uniquement doc / source / conf.py et doc / source / index.rst, et ajoutez doc / build. doc / source / module est dans .gitignore.