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.