Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Curso de introducción a Sphinx | Irontec

1,995 views

Published 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.

Published in: Technology
  • DOWNLOAD THI5 BOOKS INTO AVAILABLE FORMAT (Unlimited) ......................................................................................................................... ......................................................................................................................... Download Full PDF EBOOK here { http://bit.ly/2m6jJ5M } ......................................................................................................................... Download Full EPUB Ebook here { http://bit.ly/2m6jJ5M } ......................................................................................................................... ACCESS WEBSITE for All Ebooks ......................................................................................................................... Download Full PDF EBOOK here { http://bit.ly/2m6jJ5M } ......................................................................................................................... Download EPUB Ebook here { http://bit.ly/2m6jJ5M } ......................................................................................................................... Download doc Ebook here { http://bit.ly/2m6jJ5M } ......................................................................................................................... ......................................................................................................................... ......................................................................................................................... .............. Browse by Genre Available eBooks ......................................................................................................................... Art, Biography, Business, Chick Lit, Children's, Christian, Classics, Comics, Contemporary, Cookbooks, Crime, Ebooks, Fantasy, Fiction, Graphic Novels, Historical Fiction, History, Horror, Humor And Comedy, Manga, Memoir, Music, Mystery, Non Fiction, Paranormal, Philosophy, Poetry, Psychology, Religion, Romance, Science, Science Fiction, Self Help, Suspense, Spirituality, Sports, Thriller, Travel, Young Adult,
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • DOWNLOAD THIS BOOKS INTO AVAILABLE FORMAT (Unlimited) ......................................................................................................................... ......................................................................................................................... Download Full PDF EBOOK here { https://tinyurl.com/yyxo9sk7 } ......................................................................................................................... Download Full EPUB Ebook here { https://tinyurl.com/yyxo9sk7 } ......................................................................................................................... ACCESS WEBSITE for All Ebooks ......................................................................................................................... Download Full PDF EBOOK here { https://tinyurl.com/yyxo9sk7 } ......................................................................................................................... Download EPUB Ebook here { https://tinyurl.com/yyxo9sk7 } ......................................................................................................................... Download doc Ebook here { https://tinyurl.com/yyxo9sk7 } ......................................................................................................................... ......................................................................................................................... ......................................................................................................................... .............. Browse by Genre Available eBooks ......................................................................................................................... Art, Biography, Business, Chick Lit, Children's, Christian, Classics, Comics, Contemporary, Cookbooks, Crime, Ebooks, Fantasy, Fiction, Graphic Novels, Historical Fiction, History, Horror, Humor And Comedy, Manga, Memoir, Music, Mystery, Non Fiction, Paranormal, Philosophy, Poetry, Psychology, Religion, Romance, Science, Science Fiction, Self Help, Suspense, Spirituality, Sports, Thriller, Travel, Young Adult,
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • DOWNLOAD THIS BOOKS INTO AVAILABLE FORMAT (Unlimited) ......................................................................................................................... ......................................................................................................................... Download Full PDF EBOOK here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... Download Full EPUB Ebook here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... ACCESS WEBSITE for All Ebooks ......................................................................................................................... Download Full PDF EBOOK here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... Download EPUB Ebook here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... Download doc Ebook here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... ......................................................................................................................... ......................................................................................................................... .............. Browse by Genre Available eBooks ......................................................................................................................... Art, Biography, Business, Chick Lit, Children's, Christian, Classics, Comics, Contemporary, Cookbooks, Crime, Ebooks, Fantasy, Fiction, Graphic Novels, Historical Fiction, History, Horror, Humor And Comedy, Manga, Memoir, Music, Mystery, Non Fiction, Paranormal, Philosophy, Poetry, Psychology, Religion, Romance, Science, Science Fiction, Self Help, Suspense, Spirituality, Sports, Thriller, Travel, Young Adult,
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • DOWNLOAD THIS BOOKS INTO AVAILABLE FORMAT (Unlimited) ......................................................................................................................... ......................................................................................................................... Download Full PDF EBOOK here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... Download Full EPUB Ebook here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... ACCESS WEBSITE for All Ebooks ......................................................................................................................... Download Full PDF EBOOK here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... Download EPUB Ebook here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... Download doc Ebook here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... ......................................................................................................................... ......................................................................................................................... .............. Browse by Genre Available eBooks ......................................................................................................................... Art, Biography, Business, Chick Lit, Children's, Christian, Classics, Comics, Contemporary, Cookbooks, Crime, Ebooks, Fantasy, Fiction, Graphic Novels, Historical Fiction, History, Horror, Humor And Comedy, Manga, Memoir, Music, Mystery, Non Fiction, Paranormal, Philosophy, Poetry, Psychology, Religion, Romance, Science, Science Fiction, Self Help, Suspense, Spirituality, Sports, Thriller, Travel, Young Adult,
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • Be the first to like this

Curso de introducción a Sphinx | Irontec

  1. 1. Introduciendo Sphinx Python documentation generator www.irontec.com
  2. 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. 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. 4. Instalación apt-get install python-sphinx www.irontec.com
  5. 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. 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. 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. 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. 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. 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. 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. 12. Build • make html → index.html www.irontec.com
  13. 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. 14. Build • make html → index.html www.irontec.com
  15. 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. 16. Cambiar Theme • config.py html_theme = “agogo” html_theme_options = { "textalign": "left", "pagewidth": "50em", "documentwidth": "40em", "sidebarwidth": "10em" } www.irontec.com
  17. 17. Cambiar Theme • make html → new-page.html www.irontec.com
  18. 18. Créditos • Sphinx - http://sphinx-doc.org/ www.irontec.com
  19. 19. Irontec Internet y Sistemas sobre GNU/Linux www.irontec.com / 94 404 81 82 Ribera de Axpe 11, A116 48950 Erandio – Bizkaia

×