Sphinx¶
Estructura¶
Crear carpeta de documentación en el nivel del proyecto
$ mkdir docs
$ cd docs
Ejecutar el quickstart de sphinx para construir la estructura de directorios y el archivo de configuración
$ sphinx-quickstart
Iniciará una serie de preguntas. Mantener en default las mayoria de las opciones, pues lo importante son:
- Project name
- Source file suffix
- Version
- Makefile
- Windows bat
Template¶
En archivo conf.py editar y cambiar
html_theme = 'alabaster'
por
html_theme = 'sphinx_rtd_theme'
Comandos¶
Elementos reStructuredText¶
Para mayor información sobre los comandos se puede visitar la documentación de sphinx.
Crear nueva página¶
En index.rst se puede crear la introducción del documento. Para crear una página nueva se debe crear un documento con extensión .rst. Es importante que el documento contenga un Título para que la renderización tome el documento.
Para que Sphinx conozca el nuevo archivo debe ser registrado en el ìndex.rst en la sección del .. toctree:: con el mismo nombre del archivo, pero sin la extensión.
.. toctree::
:maxdepth: 2
nombre-archivo
Nota
El nombre del archivo debe ser identificado con la ruta, sin embargo la ruta es relativa al nivel donde se encuentra el archivo index.rst y conf.py