Sphinx autodoc no es lo suficientemente automático

112

Estoy tratando de utilizar Sphinx para documentar un proyecto de más de 5,000 líneas en Python. Tiene aproximadamente 7 módulos base. Por lo que yo sé, con el fin de utilizar autodoc tengo que escribir código como este para cada archivo en mi proyecto:Sphinx autodoc no es lo suficientemente automático

.. automodule:: mods.set.tests 
    :members: 
    :show-inheritance:

Esto es demasiado tediosa porque tengo muchos archivos. Sería mucho más fácil si pudiera especificar que quería que se documentara el paquete 'mods'. Sphinx podría examinar el paquete de forma recursiva y crear una página para cada submódulo.

¿Hay alguna función como esta? Si no, podría escribir un script para hacer todos los archivos .rst, pero eso tomaría mucho tiempo.

Fuente

2010-04-23 Cory Walker

¿Qué hay de malo en escribir un pequeño script que usa "os.walk" y escribe todo esto? Por cierto, tengo un proyecto de más de 40,000 líneas y no tengo claro de qué estás hablando. ¿Cuántos archivos están involucrados? ¿Qué tan difícil puede ser enrutar 'ls' a un archivo y editar eso? –

+98

Nadie dijo que era difícil. OP dijo que era * tedioso *, que lo es. Dado que otros sistemas de documentación pueden hacer esto, no es irrazonable. –

115

Puede consultar esta script que hice. Creo que puede ayudarte.

Este script analiza un árbol de directorios en busca de módulos y paquetes python y crea archivos ReST adecuadamente para crear documentación de código con Sphinx. También crea un índice de módulos.

ACTUALIZACIÓN

Este script es ahora parte de Sphinx 1.1 como apidoc.

Fuente

2010-04-24 04:03:35 Etienne

¿Dónde se supone que debes enviar los archivos? Traté de enviarlos a la carpeta _build predeterminada de Sphinx, pero ejecutando 'sphinx-build -b html. ./_ build' no los recoge. – Cerin

Deberías ponerlos en el 'directorio de origen' (. En tu caso). El directorio _build es donde se crearán los archivos HTML. Consulte para obtener más información: http://sphinx.pocoo.org/tutorial.html#running-the-build – Etienne

@Erienne: script fantástico! justo lo que estaba buscando. Desearía que generara encabezados para clases individuales (la apariencia regular de la esfinge no es agradable para las clases. Se pierden en módulos más grandes) – jbenet

En cada paquete, el archivo __init__.py puede tener .. automodule:: package.module componentes para cada parte del paquete.

Luego puede .. automodule:: package y en su mayoría hace lo que quiere.

Fuente

2010-04-23 21:24:15

¿Acabo de poner esa cadena entre comillas triples en __init__.py? –

@Cory Walker: No es una "cadena". Puede - y ** debería ** - poner docstrings con comillas triples en cada archivo. Todo el mundo. Eso incluye los archivos '__init __. Py' en sus paquetes. La docstring puede incluir CUALQUIER directiva de documentación de Sphinx, incluyendo '.. automodule ::' para módulos dentro del paquete. –

'autodoc' es un error tipográfico, debería ser' automodule'. ¡pero muchas gracias por la pista! – mariotomo

Quizás lo que estás buscando es Epydoc y este Sphinx extension.

Fuente

2011-01-31 14:31:19

No sé si Sphinx había tenido la extensión autosummary en el momento en que se formuló la pregunta original, pero por ahora es bastante posible configurar la generación automática de ese tipo sin usar sphinx-apidoc o script similar. A continuación hay configuraciones que funcionan para uno de mis proyectos.

Habilitar autosummary extensión (así como autodoc) en conf.py archivo y establezca su opción autosummary_generate-True. Esto puede ser suficiente si no está utilizando plantillas personalizadas *.rst. De lo contrario, agregue su directorio de plantillas para excluir la lista, o autosummary intentará tratarlos como archivos de entrada (que parece ser un error).
```
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.autosummary'] 
autosummary_generate = True 
templates_path = [ '_templates' ] 
exclude_patterns = ['_build', '_templates'] 
```
Uso autosummary:: en árbol TDC en su archivo index.rst. En este ejemplo, la documentación para los módulos project.module1 y project.module2 se generará automáticamente y se colocará en el directorio _autosummary.
```
PROJECT 
======= 

.. toctree:: 

.. autosummary:: 
    :toctree: _autosummary 

    project.module1 
    project.module2 
```
Por defecto autosummary generará sólo resúmenes muy cortos para los módulos y sus funciones.Para cambiar que se puede poner un archivo de plantilla personalizada en _templates/autosummary/module.rst (que se analiza con Jinja2):
```
{{ fullname }} 
{{ underline }} 

.. automodule:: {{ fullname }} 
    :members: 
```

En conclusión, no hay necesidad de mantener _autosummary directorio bajo el control de versiones. Además, puede ponerle el nombre que desee y colocarlo en cualquier lugar del árbol de fuentes (sin embargo, ponerlo debajo de _build no funcionará).

Fuente

2014-02-09 22:29:57 firegurafiku

Esto fue de gran ayuda. En el punto 2, donde tiene "project.module1" y "project.module2", ¿hay alguna forma de generar automágicamente esa lista para cada módulo en un paquete dado? ¿Simplemente poner "proyecto" y hacer que detecte "module1" y "module2"? – Brown

Bastante sorprendido de que no pueda encontrar una respuesta a esto en cualquier parte, ¿pero alguna vez lo resolviste @Brown? –

@AlisdairRobertson No, pero la solución de autosummary proporcionada terminó siendo más que adecuada para mis necesidades. La única otra cosa que pensé hacer fue escribir un script para generar el archivo index.rst y detectar automáticamente los nombres de los módulos. Sin embargo, en la práctica, la lista de módulos no cambia tan a menudo, por lo que simplemente editar un archivo de vez en cuando no es tan irrazonable. ¡Estoy seguro de que ya pasé mucho más tiempo buscando una solución que la que requiere editar ese único archivo! – Brown

Sphinx autodoc no es lo suficientemente automático

Respuesta

Cuestiones relacionadas