Para el propósito de esta demostración, he creado un módulo de Python. demo.py que contiene una clase y tres funciones básicas (todas anotadas con cadenas de documentos con excepción de una función). Es este módulo para el que crearé documentación en este artículo. El contenido de este módulo demo.py se encuentra a continuación:
1. Configuración
Lo primero es configurar todo. Deberá instalar VS Code y configurar un nuevo proyecto junto con Sphinx. Hay algunas opciones aquí. Puede a) configurar un nuevo proyecto usando Cookiecutter (donde se generará la configuración de Sphinx relevante junto con directorios estandarizados) o b) crear su propia estructura de proyecto e instalar sphinx por separado.
opción A: instalar Cookiecutter
En la terminal, pip instala Cookiecutter y luego crea un nuevo proyecto:
pip install cookiecutter
cookiecutter https://github.com/drivendata/cookiecutter-data-science
A continuación, responda las preguntas que aparecen en la ventana de la terminal y se creará su nuevo proyecto. El marco Sphinx se almacenará en el directorio /docs de su proyecto.
opción B: inicio rápido de Sphinx
Si la plantilla Cookiecutter no te gusta, puedes crear tu propia estructura de proyecto desde cero e instalar Sphinx. Es una buena idea crear un directorio de documentación e instalar sphinx allí. En la terminal:
mkdir docs
cd docspip install sphinx
sphinx-quickstart
2. Comprender la estructura de carpetas de Sphinx
Después de haber instalado Sphinx usando una de las opciones anteriores, aparecerán algunos archivos en el directorio de documentación de su proyecto. El conf.py El archivo es el archivo de configuración clave que editará para personalizar su documentación; encontrará más detalles sobre esto en la siguiente sección. El index.rst El archivo actúa como contenido de su documentación. Puedes encontrar más información sobre el index.rst archivo aquí. El getting-started.rst y commands.rst Los archivos son plantillas sugeridas para su documentación. Puede eliminarlos si es necesario. Los archivos de creación (make.bat y Makefile) se utilizan para realizar la documentación. No es necesario editarlos, pero los llamará en la ventana del terminal cuando esté listo para realizar la documentación.
3. Archivo conf.py
El archivo de configuración es donde ocurre la magia. Este archivo se utiliza durante el proceso de compilación, por lo que es fundamental que lo configure correctamente. A continuación se detallan algunos pasos para modificar el conf.py archivo:
Descomentar la línea sys.path (línea 20 en mi configuración):
# sys.path.insert(0, os.path.abspath('.'))
Cambiar la ruta de os.path.abspath a la ubicación relativa del código que desea documentar (en relación con el conf.py archivo). Por ejemplo, los módulos de Python que quiero documentar se encuentran dentro del directorio src/ de mi proyecto. Por lo tanto, cambiaré os.path.abspath al directorio /src que se encuentra en la carpeta principal del conf.py archivo. Puede especificar la ubicación relativa utilizando el archivo . y / sintaxis:
sys.path.insert(0, os.path.abspath('../src'))"""
# you can use the following syntax to specify relative locations:
'.' # current path of conf.py
'..' # parent path of conf.py
'../..' # parent of the parent path of conf.py
"""
Agregue las extensiones relevantes. Deberá agregar algunas extensiones al conf.py archivo para obtener funcionalidad adicional al crear su documentación. Todas ellas son opcionales y puedes divertirte explorando las diferentes extensiones disponibles. aquí. Aquí están las 5 extensiones que recomiendo como mínimo:
- esfinge.ext.autodoc – utilizar documentación de cadenas de documentos
- autodocsum — genere un resumen tabular de todas las cadenas de documentos en la parte superior de la página html enumerando únicamente los resúmenes de cadenas de documentos. Útil cuando tienes muchas cadenas de documentación. Nota. Necesitará instalar autodocsumm en la terminal.
- esfinge.ext.napoleon — permite a Sphinx analizar cadenas de documentos de Google
- esfinge.ext.viewcode — agrega un enlace a una página html que contiene el código fuente de cada módulo
- esfinge.ext.cobertura : proporciona un resumen de cuántas clases/funciones, etc. tienen cadenas de documentos. Una buena cobertura significa que una base de código está bien explicada.
Aquí se explica cómo incluir estas extensiones en el conf.py archivo (línea 29 en mi configuración):
# add in the extension names to the empty list variable 'extensions'
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.napoleon',
'autodocsumm',
'sphinx.ext.coverage'
]# add in this line for the autosummary functionality
auto_doc_default_options = {'autosummary': True}
cambiar el tema. El tema predeterminado de la documentación es bastante limpio, aunque es posible que prefieras jugar con diferentes opciones cambiando la variable ‘html_theme’ (línea 94 en mi configuración) de ‘predeterminada’ a una de las estándar. Opciones de tema o algunos opciones de terceros. En esta demostración, mostraré los temas predeterminados y Leer los documentos.
html_theme = 'sphinx_rtd_theme' # read the docs theme. This variable is 'default' by default.
Nota. deberá instalar cualquier tema no estándar (de terceros).
4. Crea las páginas html.
Ahora que tu conf.py El archivo está configurado y tiene gloriosas cadenas de documentos en su código, estamos listos para raspar un poco y crear algunas páginas html.
Genere archivos .rst de sus paquetes de Python
Estos archivos son los precursores de las páginas html y son el formato nativo de Sphinx. Estos deben generarse antes de crear los archivos html. Usarás el esfinge.apidoc comando, que utiliza la extensión autodoc para ubicar todos los módulos de Python (por ejemplo, cualquier archivo .py) dentro de la ubicación sys.path que especificó en el conf.py archivo. Hay algunos parámetros opcionales para incluir al usar el comando apidoc que puede encontrar en el documentaciónpero utilicé la siguiente plantilla:
Nota. en la terminal, cambie el directorio a la raíz del proyecto para ejecutar el siguiente código.
sphinx-apidoc -f -o output_dir module_dir/
-F (forzar la sobrescritura de cualquier archivo generado existente).
-o dir_salida (directorio para colocar los archivos de salida. Si no existe, se crea). Nota. reemplace ‘output_dir’ con un nombre de directorio de su elección. Configuré el mío en el directorio /docs.
dir_modulo (ubicación de los paquetes de Python para documentar)
Después de ejecutar este comando, debería haber archivos .rst recién generados en la carpeta de documentos.
Observe que se han generado dos nuevos archivos .rst: data.rst y modules.rst. Además de modules.rst, se generará un archivo .rst para cada directorio que contenga al menos un módulo de Python. En mi ejemplo, data.rst se genera ya que guardé mi archivo demo.py en src/data directorio. Si tiene varios directorios de módulos de Python dentro de la ubicación que especificó en sys.path en el conf.py archivo, se generarán varios archivos .rst. Nota. Estos archivos no contienen la documentación eliminada todavía, solo contienen la información necesaria para que autodoc cree los archivos html en el siguiente paso.
Editar archivo index.rst
Recordar, index.rst actúa como una página de contenido, por lo que debemos editar este archivo para incluir todos los módulos de Python que queremos documentar. Por suerte, el modules.rst hace referencia a la ubicación de origen de todos los módulos de Python identificados en sys.path, por lo que simplemente puede agregar este archivo a index.rst.
Para hacer esto, abra el index.rst archivo y agregue ‘módulos’ debajo de la sección toctree (árbol de tabla de contenido). Asegúrese de que haya una línea entre el parámetro :max Depth: y los nombres de los archivos .rst.
Nota. ‘Getting-started’ y ‘Commands’ ya estarán en el archivo index.rst. Puede eliminarlos de este archivo si no desea generar páginas html (aunque una página de “introducción” probablemente sea una buena idea).)
hacer archivos html
Ahora podemos usar los archivos make en su directorio de documentación para crear los archivos html. Estos archivos aparecerán en el _construir/html/ directorio dentro de su carpeta de documentación. Puede obtener una vista previa de estos en código VS si descarga la extensión ‘Vista previa HTML’.
Cambie el directorio donde se encuentra el archivo make.bat y ejecute el siguiente comando en la terminal cmd:
make html
Nota. Si está utilizando el terminal Windows PowerShell (en lugar de cmd), utilice la siguiente sintaxis:
.\make.bat html
Consejo superior. Si surge una advertencia al usar el comando make html que dice “autodoc: no se pudo importar el módulo”, lo más probable es que esto se deba a que autodoc no pudo encontrar sus módulos ya que sys.path no se configuró correctamente en conf.py. Asegúrese de que esto apunte al directorio donde se encuentran sus módulos de Python.
Editar archivos html
Si desea editar sus cadenas de documentación y actualizar sus archivos html con los cambios, puede hacerlo usando el siguiente comando:
make clean html
¡Echemos un vistazo a nuestra documentación!
Como mencioné anteriormente, he creado documentación de mi módulo de Python. demo.py en dos temas diferentes que se ven en las imágenes a continuación; ‘predeterminado’ (imagen de la izquierda) y ‘Leer los documentos’ (imagen de la derecha). El contenido es idéntico pero la apariencia es diferente. Tomemos nota de las características principales:
- Barra de navegación en el lado izquierdo
- Un resumen de todas las clases o funciones pertenecientes al módulo en tablas en la parte superior de la página (gracias a la extensión ‘autodocsumm’)
- Lista detallada de componentes de cadena de documentación para todas las funciones y clases debajo del resumen