Un tutorial simple sobre cómo documentar su proyecto Python usando Sphinx y Rinohtype

Documentar el código es una de las tareas que realmente no quiero hacer, pero lo haré para las calificaciones de todos modos.

Esto es probablemente lo que oirá de mí cuando era estudiante de informática de primer año. El código de documentación me pareció aburrido e inútil, ya que sé lo que hace mi código y la única persona que probablemente lo leerá es el profesor que lo revisa.

No entendí su importancia hasta que un día, tuve que mirar ese código indocumentado que escribí hace años como referencia y, en lugar de solo hojearlo, pasé mucho tiempo confundido sobre cómo estructuré el proyecto e incluso cómo ejecutarlo

Hoy en día, hay muchas herramientas disponibles para ayudarnos a documentar el código. Recientemente, aprendí sobre herramientas que facilitan la creación de documentación inteligente y hermosa. Dos de ellos son Sphinx y Rinohtype.

Sphinx, escrito por Georg Brandl y licenciado bajo la licencia BSD, fue creado originalmente para la documentación de Python y tiene excelentes instalaciones para la documentación de proyectos de software en una variedad de idiomas (Sphinx-doc.org, 2018).

Rinohtype, junto con Sphinx, ofrece una alternativa moderna a LaTeX. Proporciona un backend de Sphinx que permite generar documentos PDF con composición tipográfica profesional (Machiels).

En este tutorial, usaré Sphinx y Rinohtype para producir archivos de documentación HTML y PDF, respectivamente, en un proyecto API simple que escribí que gestiona una lista de registros del Profesor (Enlace del Proyecto Github).

  1. Clone el proyecto y elimine / mueva la carpeta de documentos para que pueda seguirme en la creación de la nueva documentación.
  2. Vaya al directorio raíz del proyecto.
  3. Crear y activar un entorno virtual de Python 3
virtualenv -p python3 
fuente  / bin / enable
Aquí llamé a mi entorno virtual

4. Instale todos los requisitos del proyecto.

pip install -r required.txt

Nota: Sphinx y Rinohtype ya están dentro del archivo require.txt. Si desea instalarlos en el entorno virtual del proyecto en el que está trabajando, use los siguientes comandos a continuación.

pip install Sphinx
pip install rinohtype

5. Cree un directorio de documentos y un CD en este directorio.

documentos mkdir
cd docs

6. Configurar Sphinx

inicio rápido de la esfinge
Siga esta configuración por ahora. Puede reconfigurar esto más tarde por su cuenta.continuación de la imagen anterior

7. Código abierto / conf.py

  • Configurar ruta al directorio raíz
Descomente las líneas 15–17Cambie la ruta a

La ruta debe apuntar al directorio raíz del proyecto y mirar la estructura del proyecto, desde conf.py debemos llegar a la raíz subiendo dos directorios principales.

Estructura del proyecto
  • Agregar Rinohtype a la lista de extensiones
'rinoh.frontend.sphinx'
  • Descomenta los elementos de látex
descomentar estosPuede cambiar el formato aún más, estos son solo los predeterminados.

8. Abra index.rst y cambie el contenido a lo siguiente. (Haga clic en el enlace index.rst para ver el contenido completo)

Documentación para el Código
**************************
.. toctree ::
   : maxdepth: 2
   : subtítulo: Contenido:

ProfesorAPI principal
===================
.. automodule :: app
   : miembros:

Controlador TeacherAPI
=====================
.. automodule :: teacherAPI.controller
   : miembros:

Modelos de TeacherAPI
=================
.. automodule :: teacherAPI.models
   : miembros:

Base de datos de TeacherAPI
===================
.. automodule :: teacherAPI.database
   : miembros:

TeacherAPI poblar
===================
.. automodule :: teacherAPI.populate
   : miembros:

9. Cree los archivos de documentación HTML y PDF.

  • Aún dentro del directorio de documentos ejecute
hacer html
sphinx-build -b rinoh source _build / rinoh

NOTA DE EDICIÓN [16 de marzo de 2019]: la creación del archivo pdf fallaría si su versión de Python es ≥3.7.0 (referencia del problema de Github)

La primera línea produciría el archivo HTML en docs / build / html / index.html

Vista de index.htmlVista de index.html

La segunda línea produciría el archivo PDF en docs / _build / rinoh / SimpleTeacherDataAPI.pdf

Página de título de la documentación.Tabla de contenidoPágina de muestra de la documentación.

Después de experimentar estar en proyectos de equipo, comencé a desarrollar mi aprecio por documentar el código y, aunque no diría que es la tarea que más disfruta, definitivamente es confiable y debería ser practicada por programadores .

Para aprender más sobre Sphinx:

  • Descripción general: documentación de Sphinx 1.8.0+

Otros tutoriales útiles:

  • Documentar su proyecto usando Sphinx: esto me ayudó a comprender cómo documentar mi código usando las cadenas de documentos de Python.
  • Tutorial de Brandon sobre la esfinge: extenso tutorial sobre el uso de la esfinge

Machiels, Brecht. "Rinohtype: El procesador de documentos Python - Rinohtype 0.3.1.Dev0 Documentation". Rinohtype.readthedocs.io. N.p., 2016. Web. 17 de junio de 2018.

Sphinx-doc.org. (2018) Descripción general: documentación de Sphinx 1.8.0+. [en línea] Disponible en: http://www.sphinx-doc.org/en/master/ [Consultado el 17 de junio de 2018].