La documentación bien escrita es crucial para casi cualquier proyecto de ciencia de datos, ya que mejora la claridad, facilita la colaboración y garantiza la reproducibilidad. La documentación clara y concisa proporciona contexto para los objetivos, metodologías y hallazgos del proyecto, lo que facilita que otros miembros del equipo (especialmente, novatos) y las partes interesadas comprendan el significado detrás del trabajo realizado. Además, la documentación sirve como referencia para futuras mejoras o la resolución de problemas, reduciendo el tiempo dedicado a volver a explicar o incluso refrescar los conceptos principales.
Suena atractivo, ¿no? Pero, ¿sabe que puede crear documentación funcional a través de la herramienta de documentación Sphinx en un estilo consistente simplemente utilizando documentos? Si aún no sabe demasiado sobre la funcionalidad de Sphinx, esta publicación puede ayudarlo a resolverlo.
Pocas palabras sobre documentos
Las documentos son los bloques de comentarios que aparecen en cualquier clase, método de clase y función dentro del código.Tres formatos de documentos principales se admiten oficialmente a través de Sphinx: Google [1]Numpy [2]y reestructuredText (reposo) [3]. El cual elegir depende de usted, pero en esta publicación trabajaré con el formato de descanso, debido a su versatilidad.
En este artículo, le presentaré tres funcionalidades más impresionantes de la herramienta de Sphinx, que puede generar automáticamente documentación para los módulos de Python. Antes de considerar estos tres casos, supongo que ya ha creado un directorio de documentación e instaló Sphinx en su máquina. Si no, por favor, lea el artículo de TDS sobre cómo instalar y configurar Sphinx primero [4].
Después de instalar Sphinx, cree un nuevo proyecto Sphinx por comando sphinx-quickstart. Siga las indicaciones para configurar su proyecto. Esto llenará su directorio con varios archivos, incluido conf.py y index.rst.
Caso 1. Use referencias cruzadas para una navegación rápida
Según el sitio web oficial de Sphinx, una de sus características más útiles es crear referencias transversales automáticas a través de roles semánticos de referencia cruzada. Las referencias cruzadas se pueden usar para vincularse a funciones, clases, módulos e incluso secciones dentro de su documentación.
Por ejemplo, la referencia cruzada a una descripción del objeto, como :func:`.name`creará un enlace al lugar donde name() está documentado.
Examinemos cómo es en la práctica. Imagina que tenemos un módulo de pitón simple llamado mymodule.py con dos funciones básicas en el interior.
La primera función es sobre sumar dos números:
def add(a: int, b: int) -> int:
"""
Add two numbers.
:param a: First number.
:param b: Second number.
:return: Sum of a and b.
"""
return a + bEl segundo se trata de restar un número del otro:
def subtract(c: int, d: int) -> int:
"""
Subtract two numbers.
:param c: First number.
:param d: Second number.
:return: Subtracting d from c.
"""
return c - dEs posible usar :func: para crear referencias cruzadas a estas dos funciones dentro de la documentación (:func:.add, :func:.subtract). Creemos otro archivo (main.py), que usará las funciones de mymodule.py. Puede agregar documentos aquí si desea documentar este archivo también:
from mymodule import add, subtract
def main():
"""
Main function to demonstrate the use of two functions.
It uses :func:`.add` and :func:`.subtract` functions from mymodule.py.
"""
# Call the first function
first = add(2,3)
print(first)
# Call the second function
second = subtract(9,8)
print(second)
if __name__ == "__main__":
main()Para generar automáticamente la documentación desde su código, puede habilitar la extensión de Autodoc en su conf.py archivo. Agregar 'sphinx.ext.autodoc' a la lista de extensiones:
extensions = ['sphinx.ext.autodoc']
Asegúrese de incluir el camino a su módulo para que Sphinx pueda encontrarlo. Agregue las siguientes líneas en la parte superior de conf.py:
import os
import sys
sys.path.insert(0, os.path.abspath('../src')) # mymodule.py and main.py are located in src folder in documentation directoryEntonces necesitamos generar .rst Archivos de nuestros paquetes de Python. Son el formato propio de Sphinx y deben generarse antes de hacer archivos HTML. Es más rápido usar el apidoc ordenar para tratar con .rst. Ejecutar en la terminal:
sphinx-apidoc -o source srcAquí -o source Define el directorio para colocar los archivos de salida y src Establece la ubicación de los módulos de Python que necesitamos describir. Después de ejecutar este comando, recién generado .rst Los archivos aparecerán en su carpeta.
Finalmente, navegue a la carpeta de su documentación y ejecute:
make htmlEsto generará documentación HTML en el _build/html directorio. Abra los archivos HTML generados en un navegador web. Debe ver su documentación con referencias cruzadas a las funciones Agregar y Restar:
Haga clic aquí en los nombres de funciones y será llevado a una página con su descripción:
Caso 2. Agregar enlaces a recursos externos
Además de la capacidad de insertar referencias cruzadas, Sphinx le permite agregar enlaces a recursos externos. A continuación se muestra un ejemplo de cómo puede crear una función en mymodule.py archivo que utiliza el incorporado abs() función para demostrar cómo es posible agregar un enlace a la documentación oficial de Python en sus documentos:
def calculate_distance(point1, point2):
"""
Calculate the distance between two points in a 2D space.
This function uses the built-in `abs()` function to compute the absolute
differences in the x and y coordinates of the two points.
For more details, see the official Python documentation for `abs()`:
`abs() <https://docs.python.org/3/library/functions.html#abs>`_.
"""
a, b = point1
c, d = point2
# Calculate the differences in x and y coordinates
delta_x = abs(c - a)
delta_y = abs(d - b)
# Calculate the Euclidean distance using the Pythagorean theorem
distance = (delta_x**2 + delta_y**2) ** 0.5
return distanceCorrer make html El comando para este caso le proporciona la siguiente salida:
Caso 3. Crear directivas y ejemplos especiales para obtener mejores efectos visuales
En Sphinx puede crear párrafos cortos con diferentes advertencias, mensajes y advertencias, así como con ejemplos concretos de resultados obtenidos. Enriquecemos nuestro módulo con una directiva y ejemplo de nota.
def calculate_distance(point1, point2):
"""
Calculate the distance between two points in a 2D space.
This function uses the built-in `abs()` function to compute the absolute
differences in the x and y coordinates of the two points.
For more details, see the official Python documentation for `abs()`:
`abs() <https://docs.python.org/3/library/functions.html#abs>`_.
Example:
>>> calculate_distance((1, 2), (4, 6))
5.0
.. note::
There is a function that calculates the Euclidean distance directly - `math.hypot() <https://docs.python.org/3/library/math.html#math.hypot>`_.
"""
a, b = point1
c, d = point2
# Calculate the differences in x and y coordinates
delta_x = abs(c - a)
delta_y = abs(d - b)
# Calculate the Euclidean distance using the Pythagorean theorem
distance = (delta_x**2 + delta_y**2) ** 0.5
return distanceY la página HTML resultante se ve lo siguiente:
Por lo tanto, para agregar cualquier ejemplo dentro de las documentos que necesita usar >>>. Y para especificar una nota allí, solo usa .. note::. Lo bueno es que puede agregar enlaces a recursos externos dentro de la nota.
Conclusión
La documentación exhaustiva permite que otros no solo comprendan mejor el tema de la lectura, sino que interactúen profundamente con ella, lo cual es esencial para la documentación técnica y científica. En general, una buena documentación promueve la transferencia de conocimiento eficiente y ayuda a mantener la longevidad del proyecto, contribuyendo en última instancia a su éxito e impacto.
En esta publicación consideramos cómo crear una documentación simple pero bien escrita utilizando la herramienta de documentación Sphinx. No solo aprendimos cómo crear un proyecto Sphinx desde cero, sino que también nos dimos cuenta de cómo usar su funcionalidad, incluidas las referencias cruzadas, los enlaces a recursos externos y directivas especiales. ¡Espero que este conocimiento te haya resultado útil para ti!
Nota: Todas las imágenes en el artículo fueron hechas por el autor.
Referencias
[1] Guía de estilo de Google Python: https://google.github.io/styleguide/pyguide.html hacer html
[2] Guía de estilo Numpy: https://numpydoc.readthedocs.io/en/latest/format.html
[3] Guía de estilo reestructuredText: https://docutils.sourceforge.io/rst.html
[4] Publicar “Paso a paso básicos: Código Autodocumentación”: https://towardsdatascience.com/step-by-step-basics-code-autodocumentation-fa0d9ae4ac71
[5] Sitio web oficial de la herramienta de documentación de Sphinx: https://www.sphinx-doc.org/en/master/