Crear documentación de un proyecto Python con Sphinx.

LaTeX

Si deseamos generar documentación web, este paquete no es necesario, pero para generar nuestra documentación en PDF es una dependencia obligatoria. La instalación recomendada dependerá del sistema operativo que se use.

Mac

Puedes usar MacTex el cual incluye el compilador TeXLive y editores como TeXShop, y otras dependencias para el funcionamiento de LaTeX en Mac.

Windows

La opción más cómoda es el compilador MikTeX, el cual permite de forma predeterminada la descarga automática de paquetes adicionales en la medida que sean requeridos (instalación on the fly).

Es importante que en la configuración no cambies al modo silencioso, pues esto puede afectar la ejecución posterior en los casos que requieran de instalación.

Si usas Anaconda, puedes incluirlo desde el canal de conda-forge, conda install -c conda-forge miktex.

En la primera forma de instalación requieres instalar Perl, en la segunda, este viene como dependencia instalada por el gestor de paquetes. También puedes usar TeXLive para Windows, el cual asegura la consistencia en el resultado entre los 3 sistemas operativos.

Linux

En Linux usaremos TeXLive pero su instalación la haremos directamente del gestor de paquetes del sistema operativo. En la mayor parte de distribuciones Linux estará disponible a través del gestor.

En el caso de las distribuciones basadas en Debian (Ubuntu y Linux Mint entre otras) puedes instalar de la siguiente manera:

sudo apt install -y texlive texlive-latex-base texlive-latex-extra \
    texlive-lang-spanish latexmk

Sphinx

Si usamos Python a través de Anaconda podemos usar el gestor conda para la instalación, así conda install sphinx, en caso contrario, podemos usar el gestor de paquetes PIP: pip install -U Sphinx.

Configuración de Sphinx

Abriremos una consola (si es Windows, debes tener en cuenta que para usar paquetes de Anaconda debes usar las consolas Anaconda Prompt, Anaconda PowerShell u otra si la configuraste -como el caso de Git Bash que mencioné en la sección anterior-) y debemos ubicarnos en el directorio que destinaremos para la documentación. Es habitual que en la estructura de nuestro proyecto destinemos un directorio docs para este fin.

Ahora ejecutamos sphinx-quickstart y respondemos las preguntas que saldrán. Es necesario tener en cuenta, que si usas Windows debes agregar al comando la terminación .exe, ejemplo sphinx-quickstart.exe.

> Separate source and build directories (y/n) [n]: y
> Project name: proyecto
> Author name(s): Edward Villegas-Pulgarin
> Project release []: 0.1.0
> Project language [en]: es

Siempre recomiendo separar el directorio del código fuente de la documentación del directorio de compilados de la misma. Respecto al esquema de versiones me agrada el versionamiento semántico que permite al usuario final intuir un poco más sobre la madurez del proyecto con el número, pero puedes usar el esquema basado en fecha de liberación. En el lenguaje se especifica el lenguaje con el código a dos letras internacional, acorde a los soportados por Sphinx.

Aunque en la terminal nos indican que podemos continuar con el archivo index.rst, debemos hacer unos pequeños cambios en el archivo conf.py que encontraremos en docs/source.

Puedes saber más opciones de configuración en la documentación de Sphinx sobre conf.py.

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.mathjax',
    'sphinx.ext.napoleon',
    'sphinx.ext.coverage',
    'sphinx.ext.doctest'
]

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

author = proyecto.__author__
copyright = str(datetime.date.today().year) + ', ' + author
release = proyecto.__version__

autodoc_mock_imports = ["tensorflow", "arcpy"]

numfig = True
numfig_format = {'figure': 'Fig. %s', 'table': 'Tabla %s',
                 'code-block': 'Código %s', 'section': 'Sección %s'}
numfig_secnum_depth = 1
math_numfig = True
math_eqref_format = 'Ec. {number}'

master_doc = 'index'
latex_documents = [
    (master_doc, 'proyecto.tex', 'Documentación Proyecto',
     author, 'manual'),
]

Escritura en ReStructuredText

Sobre esto, es referencia ver la documentación de DocUtils y de Sphinx ReStructuredText Primer.

Una vez tienes las bases de ReStructuredText puedes editar lo básico. De ahí, y para tener todo el provecho de Sphinx hay elementos como los roles, directivas y dominios que debes aprender a usar, Sphinx ReStructuredText.

¿Y por qué los dominios? Estos añaden sintaxis para manejar las relaciones con el código, como enlazar a funciones relacionadas que se generaron con autodoc y además la forma de como documentar la función (u otro elemento del código) en su código fuente y que pueda ser extraída. Por ejemplo, el dominio de Python.

.. toctree::
   :maxdepth: 3
   :caption: Contenido:

   README
   installation
   usage
   api/modules
   concepts
   history

Ejecución de Sphinx

Como estamos haciendo uso de autodoc, nuestro primer paso es generar la extracción de la API.

sphinx-apidoc -f -M -o source/api/ ../proyecto

Recordar que en Windows hay que agregar .exe (sphinx-apidoc.exe). -f es para forzar la regeneración de los archivos (importante si actualizamos la documentación de la API), -M para ubicar primero la documentación de los módulos (por defecto primero son las funciones, y esto no me parece natural). Luego, es la ruta para la documentación de la API (uno de los archivos será el api/modules.rst) y finalmente la ruta donde se encuentra el paquete. Ambas rutas son relativas al directorio de documentación.

Ahora, solo es necesario generar la documentación: make latexpdf si es con el Makefile o make.bat latexpdf si no instalaste make en Windows. Aquí debemos devolvernos un nivel en la carpeta para ejecutarlo.

Publicar

Ahora encontrarás en la carpeta build los archivos LaTeX, y uno de ellos será el PDF que queremos. También puedes hacer compilación HTML (make html) y usar esta para publicar como un GitHub Pages o en ReadTheDocs.