[PYTHON] Integration von Sphinx-Apidoc-Setuptools

Ich habe eine bessere Vorgehensweise als unten veröffentlicht (http://qiita.com/koreyou/items/00f5820591ec9196ef07). Ich denke, die Praxis in diesem Beitrag ist auch abhängig von den Bedingungen gültig, also werde ich sie vorerst verlassen.

Einführung

sphinx-apidoc ist ein leistungsstarkes Tool zur Automatisierung der Erstellung von API-Dokumentationen. Es gibt ein Sphinx-Integrationswerkzeug in Setuptools, aber um Sphinx-Apidoc zu verwenden, muss Sphinx-Apidoc einmal mit CLI ausgeführt und dann Sphinx mit Setuptools usw. erstellt werden. Automatisierung ist nicht gut //github.com/sphinx-doc/sphinx/issues/1135). In diesem Beitrag wird beschrieben, wie Sie sowohl Sphinx-Apidoc als auch Sphinx in einem Befehl ausführen.

Übrigens bin ich nicht an der OSS-Entwicklung beteiligt, daher bin ich mir nicht sicher, ob das Folgende eine gute Praxis ist.

Methode

Vorbereitung

Installieren Sie Sphinx und erstellen Sie ein Dokumentationsverzeichnis.

$ pip install sphinx 
$ sphinx-quickstart

Folgen Sie dem Schnellstart, um die Fragen entsprechend auszufüllen. Im Folgenden finden Sie eine Sammlung nur der Fragen, die für diesen Ansatz beantwortet werden müssen.

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

Anschließend wird unter dem Verzeichnis ein Verzeichnis "doc /" mit der folgenden Struktur erstellt.

.

├── doc/
│   ├── build/
│   └── source/
│       ├── _build/
│       ├── conf.py
│       ├── index.rst
│       ├── _static/
│       └── _templates/
├── README.md
├── setup.cfg
├── setup.py
├── test/
├── my_project/

Fügen Sie Code für den Build hinzu

Schreiben Sie setup.py wie folgt. Wenn Sie nur Sphinx verwenden, schreiben Sie nur "setup (cmd class = {'build_sphinx': BuildDoc}, ...)", aber dieses Mal hat er "BuildDoc" geerbt und "apidoc" als Vorverarbeitung hinzugefügt. Definieren Sie einen neuen Befehl.

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'],
)

Schreiben Sie außerdem einige Dateien neu.

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/*

Lauf

python setup.up build_sphinx

Nachdem verschiedene Informationen übergeben wurden, sollte die API-Dokumentation unter "doc / build / html / index.html" erstellt werden, wenn sie normal beendet wird.

In Bezug auf die Versionsverwaltung wird "doc / source / modules" automatisch generiert. Geben Sie daher nur "doc / source / conf.py" und "doc / source / index.rst" ein und fügen Sie "doc / build" hinzu. doc / source / module ist in .gitignore.

Referenz

• Stackoverflow, "Autogenerate documentation for Python project using setuptools"