Autogenerar documentación para proyectos Python usando setuptools

python-sphinx api-doc

Question

He creado un proyecto de demostración que utiliza setuptools y tiene la siguiente estructura:

project/
 |- pizza/
 |   |- __init__.py
 |   `- margherita.py
 |
 |- README.rst
 |- setup.cfg
 `- setup.py

Estoy tratando de generar automáticamente la documentación para este proyecto usando Sphinx. Hasta ahora he intentado:

# Generate a sphinx template
sphinx-quickstart
# Use default settings, except for project name, etc.
sphinx-apidoc -o source .
./setup.py build_sphinx

Creo que tiene que haber una manera más fácil de setup.py automáticamente esta documentación utilizando README , setup.py y docstrings.

En última instancia, me gustaría autogenerar apidocs para otro proyecto en el que también uso la Python C-api. No pude encontrar nada para esto.

Mi pregunta principal es: ¿Existe una forma más fácil de generar automáticamente esta documentación?

Answer 1

Para extender setup.py para que contenga un comando adicional para Sphinx, puede crear un comando personalizado. He cocinado un pequeño ejemplo que ejecuta Sphinx apidoc y luego crea las fuentes de documentos. Se utilizan el nombre del proyecto, el autor, la versión y la ubicación de las fuentes definidas en setup.py (asumiendo que están definidas).

class Sphinx(Command):
    user_options = []
    description = ''sphinx''

    def initialize_options(self):
        pass

    def finalize_options(self):
        pass

    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(
            ['''', ''--full'', ''-H'', metadata.name, ''-A'', metadata.author,
             ''-V'', metadata.version, ''-R'', metadata.version,
             ''-o'', os.path.join(''doc'', ''source''), src_dir])
        # build the doc sources
        sphinx.main(['''', os.path.join(''doc'', ''source''),
                     os.path.join(''doc'', ''build'')])

Luego, el comando debe registrarse en el grupo de puntos de entrada distutils.commands . Aquí el comando se llama sphinx .

from setuptools import setup

setup(
    # ...
    setup_requires = [''sphinx''],
    entry_points = {
        ''distutils.commands'': [
            ''sphinx = example_module:Sphinx''
        ]
    }
)

No sé cómo se manejan las fuentes de C, pero esto te ayudará a comenzar.

Answer 2

sphinx-apidoc -F -o source .

Generará un proyecto con sphinx-quickstart y buscará recursivamente módulos de python

Eres tan eficiente como puedes ser en este momento.

=== Pensamientos ilusorios debajo de aquí ===

¿No sería maravilloso si pudieras llamar algo así?

./setup.py build_sphinx -C

y te crearía tu índice. RST, leería los archivos RST que tenías tocando, analizaba todas las cadenas de documentación y escupía algunos html.