Curso de introducción a Sphinx, una herramienta para facilitar la generación de documentación. Originalmente pensado para generar documentación en proyectos de Python.

1. Introduciendo
Sphinx
Python documentation generator
www.irontec.com

2. Qué es
•
Herramienta para facilitar la generación de documentación.
•
Originalmente pensado para generar documentación en proyectos de Python
www.irontec.com

3. Características
•
Soporta varios tipos de salida (builders): HTML, LaTeX, Pdf, ePub, Texinfo, man
pages, texto plano.
•
Permite referencias cruzadas
•
Estructurado jerárquicamente
•
Generación automática de índices
•
Soporte para coloreo de código (usando pygments)
•
Soporta extensiones
•
Usa reStructuredText como lenguaje de marcado (docutils)
www.irontec.com

4. Instalación
apt-get install python-sphinx
www.irontec.com

5. ReStructuredText
•
•
Parrafos: Se escriben con una línea en blanco entre ellos.
Negritas, cursivas, códigos literales, subíndices, superíndices, enlaces,
etc.
–
–
Marcado Estandar: *Cursiva*, **Negrita**, ``Código literal``
Roles: Se escriben con dos puntos antes y después del nombre del rol,
seguido del texto que se desea utilizar entrecomillado.
● :rolname:`Texto que queremos marcar`
● Permiten realizar enlaces dentro del documento y/o entre documentos
– :ref:, :doc::download:, etc
● Permiten formatear el texto de forma semántica:
– :abbr: , :command:, :file:, :kbd:, :mimetype:, etc.
www.irontec.com

6. ReStructuredText
•
Listas: Se generan poniendo asteríscos, números o almohadillas al inicio de cada línea
* Lista con viñeta.
* Con dos elementos
el segundo de dos lineas.
* Y esto es un elemento en una sublista
1. Lista numerada
2. Con dos elementos
#. Esto es una lista autonumerada.
–
#. Y tiene dos líneas también.
Otros tipos de listas:
● Glosarios de terminos usando “term”
● Bloques de texto indentados dejando espacios en el inicio de línea
● Etc.
www.irontec.com

7. ReStructuredText
•
Bloques de código literales: Se inician poniendo dobles dos puntos al final de una línea e indentando todo el código que lo acompaña.
Lo que viene debajo de este texto es un código en PHP::
<?php
echo “hola mundo”
•
Tablas: Se pueden generar de múltiples maneras
–
Pintándolas completamente usando los siguientes caracteres: =-+|
+------------------------+------------+----------+----------+
| Header row, column 1
| Header 2
| Header 3 | Header 4 |
+========================+============+==========+==========+
| body row 1, column 1
| column 2
| column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2
| ...
| ...
|
|
+------------------------+------------+----------+----------+
–
De forma más simple pero limitada
=====
=====
=======
A
B
A and B
=====
=====
=======
False
False
False
True
False
False
=====
=====
=======
www.irontec.com

8. ReStructuredText
•
•
Enlaces: Si el texto del enlace es el propio enlace no hay que hacer nada, si queremos ponerle un texto:
`Texto del enlace <http://example.com/>`_
– Atención: Si se quiere enlazar a documentos internos se usa el rol :ref:
Secciones: Las secciones se generan subrayando los títulos de las mismas.
–
Caracteres que sirven para el subrayado: ! " # $ % & ' ( ) * + , - . / : ; < = > ?
@ [ ] ^ _ ` { | } ~
–
–
Recomendados: = - ` : . ' " ~ ^ _ * + #
Los títulos de las secciones pueden llevar también un “sobrerayado”
=================
Esto es un título
=================
Y esto un subtítulo
–------------------
–
Atención: El subrayado debe coincidir exactamente con la longitud del título
www.irontec.com

9. ReStructuredText
•
Directivas: Junto con los roles es el mecanismo de extensión de Sphinx.
–
Se declaran de la siguiente manera:
.. tipo directiva:: directiva
:option1: value1
:option2: value2
–
bloque
Las directivas por defecto que soporta Sphinx permiten entre otras cosas:
● Añadir notas (avisos, mensajes, anotaciones, etc.)
● Añadir imágenes
● Añadir bloques de texto especiales
● Crear tablas a partir de fuentes alternativas (csv, listas, …)
● Generación de tags html
● Crear roles
www.irontec.com

10. Primeros Pasos
•
Crear un nuevo proyecto de Sphinx
–
sphinx-quickstart
● Asistente de instalación que permite generar la estructura inicial de un
proyecto a partir de un conjunto de preguntas
● Genera:
– index.rst: Documento inicial desde el que partirá toda la
documentación
– conf.py: Configuración del proyecto (theme, rutas, propiedades,
etc.)
– Makefile: Preparado para permitir generar la documentación
directamente con “make <builder>”
www.irontec.com

11. Build
•
index.rst
Welcome to Test's documentation!
================================
Contents:
.. toctree::
:maxdepth: 2
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
www.irontec.com

12. Build
•
make html → index.html
www.irontec.com

13. Build
•
Añadiendo enlaces a otros documentos desde el “toctree”
Welcome to Test's documentation!
================================
Contents:
–-----------.. toctree::
:maxdepth: 2
new-page
new-page-2
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
www.irontec.com

14. Build
•
make html → index.html
www.irontec.com

15. inotify
•
Permite registrar los cambios dentro de un directorio y ejecutar acciones si algo ha cambiado, así evitamos tener
que hacer un make manualmente con cada cambio:
–
/usr/local/bin/inotify-sphinx.sh
#!/bin/bash
if [ ! -z "$1" ]; then
path=$1
else
path="."
fi
while true
do
inotifywait -r -e modify -e move -e create -e delete $path | while read line
do
cd $path
make html
done
done
www.irontec.com

16. Cambiar Theme
•
config.py
html_theme = “agogo”
html_theme_options = {
"textalign": "left",
"pagewidth": "50em",
"documentwidth": "40em",
"sidebarwidth": "10em"
}
www.irontec.com

17. Cambiar Theme
•
make html → new-page.html
www.irontec.com

18. Créditos
•
Sphinx - http://sphinx-doc.org/
www.irontec.com

19. Irontec
Internet y Sistemas sobre GNU/Linux
www.irontec.com / 94 404 81 82
Ribera de Axpe 11, A116 48950 Erandio – Bizkaia