Curso de introducción a Sphinx | Irontec

  • 834 views
Uploaded on

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.

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.

More in: Technology
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Be the first to comment
    Be the first to like this
No Downloads

Views

Total Views
834
On Slideshare
0
From Embeds
0
Number of Embeds
4

Actions

Shares
Downloads
3
Comments
0
Likes
0

Embeds 0

No embeds

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
    No notes for slide

Transcript

  • 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