En este artículo, repasaremos los (muy) conceptos básicos de generar documentación a partir de cadenas de documentos en su código Python. Es un poco complicado, pero después de hacerlo una vez, será fácil repetir el proceso en cada nuevo proyecto.

Para nuestros propósitos, asumiremos que usted (1) cree en el valor de documentar su código; (2) desea generar documentos a partir de sus cadenas de documentos y (3), ha elegido usar Sphinx para realizar el trabajo.

Finalmente, se asume que ya ha configurado un entorno virtual distinto para su aplicación. Para aquellos interesados, me gusta mucho el gerente de medio ambiente de pyenv. Incluso tiene un práctico instalador.

Necesitará instalar sphinx a través de pip. Como mínimo, necesitará la versión 1.3, pero a menos que tenga una buena razón, debe instalar la versión más reciente.

$ pip install sphinx

Paso 2: Configure su proyecto con Inicio rápido

Al instalar el paquete sphinx, también se configuran varias utilidades de línea de comandos.

Una de ellas, sphinx-quickstart generará rápidamente un archivo de configuración básico y una estructura de directorios para su documentación.

Ejecute este comando en el directorio base de su proyecto (es decir, la raíz de repositorio de Git). Le hará una serie de preguntas que determinarán sus acciones. Generalmente puede aceptar los valores predeterminados, pero aquí hay algunas sugerencias de cuándo desviarse del valor predeterminado:

Después de que se ejecute el programa, notará que existe una nueva carpeta ./docs en el directorio de su proyecto. Además, hay tres nuevos archivos en la carpeta: conf.pyindex.rst yMakefile.

Paso 3: Ajustar el conf.py Archivo

El archivo predeterminado conf.py generado por la utilidad de inicio rápido tiene aproximadamente 170 líneas, por lo que no lo incluiré todo aquí. Sin embargo, hay un par de elementos que debemos actualizar antes de continuar.

Dile a Sphinx la ubicación de tu paquete Python

Lo primero que tenemos que hacer es indicar dónde está el paquete Python que contiene tu código de programa en relación con el archivo conf.py. Si su estructura de directorios se ve así:

Usted tendrá que indicar en la etiqueta conf.py archivo Esfinge debe ir «hasta» un nivel en el directorio para encontrar el paquete de Python.

El lugar para poner esto es al final de la primera sección del archivo de configuración. Justo antes de la configuración General Configuration, verá esto:

# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))

Si no se comenta, indicaría que su paquete está en el mismo directorio que el archivo conf.py. Deberá cambiarlo a lo siguiente:

import os
import sys
sys.path.insert(0, os.path.abspath('..'))

Agregue «Napoleon» a la lista de Extensiones de Esfinge para usar

Fuera de la caja, Sphinx solo entiende cadenas de documentos escritas en texto reestructurado tradicional. Si ha tenido el privilegio de trabajar con tales cuerdas de documentos, sabrá que son un dolor de escritura y no son fáciles de leer para los humanos cuando los mira directamente en el código fuente.

La extensión Napoleon permite a Sphinx entender las cuerdas de documentos escritas en otros dos formatos populares: NumPy y Google.

Todo lo que tenemos que hacer es agregar sphinx.ext.napoleon para el extensions lista. Cuando haya terminado, debería verse así:

extensions = 

Paso 4: Actualizar índice.rst

En este punto, podríamos ejecutar el proceso de compilación para generar nuestra documentación. Pero sería bastante decepcionante. Esto es lo que conseguiríamos:

tanto como me gustaría Esfinge para ir y encontrar nuestra docstrings para nosotros y para arreglar muy bien sin ningún tipo de configuración adicional, no es bastante mágico.

Para avanzar, tendremos que hacer algunas modificaciones menores a nuestro archivo index.rst, que actualmente se parece a este:

Comencemos por deshacernos del comentario en la parte superior, que es solo ruido:

Ahora, aunque hay una serie de cosas que podríamos hacer aquí, nos limitaremos al mínimo para mantener esta publicación a una longitud algo razonable.

¿Ves que .. toctree:: línea? Eso es lo que Sphinx llama directiva. Necesitamos agregar directivas autodoc a nuestro archivo index.rst para que Sphinx sepa en qué objetos de código queremos usar la extensión autodoc.

Seguiré adelante y agregaré uno indicando a Sphinx que quiero que documente los miembros públicos de mi módulo main.py dentro del paquete my_project:

Paso 5: Escribe tus cadenas de documentos

En este post no cubriremos cómo escribir cadenas de documentos en estilo Numpy o Google.

sin Embargo, aquí está el código de main.py que contiene un par de sencillos NumPy estilo docstrings que será recogido por nuestro autodoc directiva:

Paso 6: Generar tus documentos!

Ahora es el momento de cosechar las recompensas de su trabajo. Asegúrese de estar en el directorio ./docs y ejecute lo siguiente: make html

Si ha estado siguiendo hasta ahora, debería ver algo como esto:

Mientras vea ese glorioso mensaje build succeeded Al final, está listo para ve y contempla tu hermosa creación.

En la línea de comandos, ejecute open _build/html/index.html (o simplemente abra esa página en su navegador manualmente) y debería ver algo como esto:

Siguiente Pasos

Apenas hemos arañado la superficie de aquí y hay una gran cantidad de verrugas en nuestro simple de la documentación.

En el próximo post sobre este tema, profundizaremos en las directrices de la extensión autodoc y lograremos un mayor control del contenido y la apariencia de nuestra documentación.