sphinx-Read the Docs intégration pour apidoc

introduction

Dans un article précédent (http://qiita.com/koreyou/items/8c101802f4d38781e696), j'ai décrit comment exécuter à la fois sphinx-apidoc et sphinx avec une seule commande. Cependant, puisque cette méthode était une méthode pour changer le comportement de setuptools, pas sphinx lui-même, avec des services tels que Read the Docs qui exécute directement sphinx sans mordre setuptools. Il y avait un problème que cela ne pouvait pas bien fonctionner. Dans cet article, je décrirai comment incorporer le sphinx-apidoc directement dans l'exécution côté sphinx.

procédure

La structure des répertoires, etc. est conforme à Last Post.

Tout d'abord, intégrez sphinx-apidoc dans l'exécution de Sphinx.

doc/source/conf.py

import sphinx.apidoc


root_dir = os.path.abspath('../..') 

try:
    # This succeeds = the project is already installed.
    # This directive avoids Readthedocs to fail
    import my_project
except ImportError:
    sys.path.insert(0, root_dir)
    import my_project

# ...
# Rest of the conf.py
# ...


def run_apidoc(_):
    script_dir = os.path.dirname(os.path.realpath(__file__))
    src_dir = os.path.join(script_dir,  root_dir)
    out_dir = os.path.join(script_dir, "modules")
    sphinx.apidoc.main(
        ['', '-f', '-H', project, '-A', author,
         '-V', version, '-R', release, '-T', '-M',
         '-o', out_dir, src_dir])


def setup(app):
    app.connect('builder-inited', run_apidoc)

Il y a deux points:

1. Essayez ʻimport my_project`, et si cela échoue, essayez à nouveau d'importer via le chemin vers la racine du projet. En effet, Read the Docs crée la bibliothèque une fois, l'installe dans l'environnement local, puis crée la documentation [^ 1].
2. Accrochez l'exécution de sphinx-apidoc lorsque Sphinx est exécuté en définissant la commande setup.

[^ 1]: il s'agit d'une option pour Lire la documentation, pas du comportement par défaut. Cependant, si les bibliothèques dépendantes sont définies du côté setuptools, je pense que c'est plus intelligent que de créer requirements.txt séparément pour Read the Docs.

Si vous avez installé sphinx-apidoc dans setup.py comme dans l'article précédent, restaurez-le dans son état d'origine. Ensuite, modifiez autour de setup.py comme suit.

setup.py

cmdclass = {} 

#Sinon, vous aurez besoin de Sphinx juste pour installer la bibliothèque en tant qu'utilisateur
try:
    from sphinx.setup_command import BuildDoc
    cmdclass['build_sphinx'] = BuildDoc
except ImportError:
    pass

# ...
# Rest of the setup.py
# ...

setup(
   ...
   cmdclass=cmdclass
)

setup.cfg

[build_sphinx]
source-dir = doc/source
build-dir  = doc/build
all_files  = 1

Enfin, définissez le côté Lire la documentation.

En suivant les étapes ci-dessus, vous pouvez créer la documentation dans l'environnement de développement avec python setup.py build_sphinx, et vous pouvez également créer de la même manière à partir de Read the Docs.