[PYTHON] sphinx-Lesen Sie die Docs-Integration für Apidoc

Einführung

Im vorherigen Beitrag (http://qiita.com/koreyou/items/8c101802f4d38781e696) habe ich beschrieben, wie sowohl Sphinx-Apidoc als auch Sphinx mit einem Befehl ausgeführt werden. Diese Methode war jedoch nicht die Methode zum Ändern des Verhaltens von Setuptools selbst, sondern die Methode zum Ändern des Verhaltens von Setuptools, also mit Diensten wie Read the Docs, die Sphinx direkt ausführen, ohne Setuptools zu beißen. Es gab ein Problem, dass es nicht gut funktionieren konnte. In diesem Beitrag werde ich beschreiben, wie Sphinx-Apidoc direkt in die Ausführung auf der Sphinx-Seite integriert wird.

Verfahren

Die Verzeichnisstruktur usw. entspricht Letzter Beitrag.

Betten Sie zunächst Sphinx-Apidoc in die laufende Sphinx ein.

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)

Es gibt zwei Punkte:

1. Versuchen Sie, "my_project" zu importieren. Wenn dies fehlschlägt, versuchen Sie erneut, über den Pfad zum Stammverzeichnis des Projekts zu importieren. Dies liegt daran, dass Read the Docs die Bibliothek einmal erstellt, in der lokalen Umgebung installiert und dann die Dokumentation erstellt [^ 1].
2. Haken Sie die Ausführung von sphinx-apidoc ein, wenn Sphinx ausgeführt wird, indem Sie den Befehl setup definieren.

[^ 1]: Dies ist eine Option zum Lesen der Dokumente, nicht das Standardverhalten. Wenn die abhängigen Bibliotheken jedoch auf der Seite der Setuptools definiert sind, ist dies meiner Meinung nach intelligenter, als require.txt separat für Read the Docs zu erstellen.

Wenn Sie sphinx-apidoc wie im vorherigen Beitrag in setup.py installiert haben, stellen Sie den ursprünglichen Zustand wieder her. Ändern Sie dann um setup.py wie folgt.

setup.py

cmdclass = {} 

#Andernfalls benötigen Sie Sphinx, um die Bibliothek als Benutzer zu installieren
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

Stellen Sie abschließend die Seite "Dokumente lesen" ein.

Wenn Sie die obigen Schritte ausführen, können Sie die Dokumentation in der Entwicklungsumgebung mit "python setup.py build_sphinx" erstellen und auf die gleiche Weise auch "Read the Docs" erstellen.