Esta semana estuve trabajando en agregar la capacidad de generacion del diagrama de la Base de Datos utilizada por Neutron. Quiza sea poco probable que la Base de Datos sufra cambios frecuentes pero de cualquier forma es importante mantener la documentacion sincronizada con lo que es ofrecido por el codigo fuente.

El proceso mediante el cual se genera la documentacion en OpenStack es muy sencillo, ya que utiliza tox. Tox se define como una herramienta escrita en Python para automatizar y estandarizar pruebas en Python. Su comportamiento se especifica a traves de un archivo de configuracion llamado tox.ini donde se define la manera en que se genera los ambientes virtuales utilizados para ejecucion de pruebas unitarias y funcionales o como es nuestro caso, la generacion de documentacion.

Este archivo tiene una seccion donde se enlista los ambientes virtuales a ser creados, para el caso de Neutron solo se crearan cuatro ambientes virtuales:

• docs: Utilizado para la generacion de documentacion del proyecto
• py34: Utilizado para la ejecucion de las pruebas unitarias y funcionales para la version de Python 3.4
• py27: Utilizado para la ejecucion de las pruebas unitarias y funcionales para la version de Python 2.7
• pep8: Utilizado para la validacion de reglas para el estilo de programacion

neutron/tox.ini

[tox]
envlist = docs,py34,py27,pep8
...

Durante la ejecucion inicial se crean ambientes virtuales(en caso de no existir) y dentro de cada uno de ellos se instala los modulos enlistados en los archivos de requirements.txt y test-requirements.txt. Este proceso solo abarca aquellos modulos de python necesarios para la ejecucion de tox, todas aquellas dependencias que de sistema tendran que ser instaladas por separado, como es el caso de las bibliotecas de desarrollo de python( # apt install python-dev || dnf install python-devel) entre otras.

[testenv]
...
install_command =
                  constraints: {[testenv:common-constraints]install_command}
                  pip install -U {opts} {packages}
deps = -r{toxinidir}/requirements.txt
       -r{toxinidir}/test-requirements.txt
...
[testenv:common-constraints]
install_command = pip install -c{env:UPPER_CONSTRAINTS_FILE:https://git.openstack.org/cgit/openstack/requirements/plain/upper-constraints.txt} {opts} {packages}
...

Dentro del archivo podemos observar el comando utilizado para la generacion de documentos.

[testenv:docs]
commands = sphinx-build -W -b html doc/source doc/build/html

De tal forma que al ejecutar $ tox -e docs se creara un ambiente virtual en dentro de la carpeta ~/.tox/docs con todas los modulos necesarios para generacion de documentos y dentro de el se ejecutara el comando sphinx-build -W -b html doc/source doc/build/html. En cuanto a los parametros utilizados, W permite cambiar los mensajes de Warning por Errores, b define el builder a ser utilizado y los dos argumentos, el primero define la carpeta donde se localiza la documentacion en formato Markdown y el segundo es la carpeta para los archivos generados.

Como he mencionado previamente, sphinx es un modulo de python que nos permite generar documentacion a partir de archivos escritos en formato Markdown. Al igual que tox, su funcionamiento se basa en un solo archivo que contiene los valores de configuracion, este archivo se llama conf.py y debe localizarse dentro de la carpeta utilizada como fuente, en nuestro caso doc/source/conf.py.

Por ultimo, es importante mencionar que sphinx es una herramienta poderosa que permite extender su funcionalidad mendiante el uso de extensiones, estas son anexadas dentro del archivo de configuracion
conf.py

...
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.autodoc',
              'sphinx.ext.coverage',
              'sphinx.ext.ifconfig',
              'sphinx.ext.pngmath',
              'sphinx.ext.graphviz',
              'sphinx.ext.todo',
              'schemadisplay_sphinx',
              'oslosphinx']
...