Curso de introducción a Sphinx | Irontec
0 recomendaciones2,503 vistas
Sphinx es una herramienta para generar documentación, especialmente diseñada para proyectos de Python. Ofrece múltiples formatos de salida, generación automática de índices, y soporta restructuredtext como lenguaje de marcado, permitiendo referencias cruzadas y extensiones. Además, incluye directivas para añadir notas, imágenes y tablas, facilitando la creación y mantenimiento de documentación de manera eficiente.
![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](https://image.slidesharecdn.com/curso-sphinx-140307024540-phpapp01/85/Curso-de-introduccion-a-Sphinx-Irontec-8-320.jpg)
![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](https://image.slidesharecdn.com/curso-sphinx-140307024540-phpapp01/85/Curso-de-introduccion-a-Sphinx-Irontec-15-320.jpg)
Curso de introducción a Sphinx | Irontec
- 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
- 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
- 19. Irontec Internet y Sistemas sobre GNU/Linux www.irontec.com / 94 404 81 82 Ribera de Axpe 11, A116 48950 Erandio – Bizkaia