Curso de introducción a Sphinx | Irontec

67 %
33 %
Information about Curso de introducción a Sphinx | Irontec
Technology

Published on March 7, 2014

Author: irontec

Source: slideshare.net

Description

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.

Introduciendo Sphinx Python documentation generator www.irontec.com

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Add a comment

Related presentations

Related pages

Software libre para tu empresa | Irontec | Bilbao Spain

Software libre para tu empresa. Somos Irontec, una de las empresas pioneras de software libre y open source en Euskadi, y queremos que tomes las riendas de ...
Read more

Casos de éxito | Irontec | Bilbao Spain

Casos de éxito de Irontec relacionados con sistemas linux, centralitas ip, voip, asterisk, marketing, producción tecnológica de eventos, wordpress ...
Read more

Blog de Irontec

Blog de Irontec, empresa de software libre y negocios abiertos de Bilbao
Read more

irontec (@irontec) | Twitter

The latest Tweets from irontec (@irontec). Innovación. Tecnologías abiertas. Software libre. Desarrollo Web. Internet. VoIP. Cloud. Sistemas. Marketing.
Read more

Irontec: Internet y Sistemas sobre GNU/Linux | Facebook

Irontec: Internet y Sistemas sobre GNU/Linux, Bilbao. 559 likes · 6 talking about this · 276 were here. Internet y Sistemas sobre GNU/Linux
Read more

Irontec: Android-Applikationen mit PHP entwickeln - Golem.de

Irontec Android-Applikationen mit PHP entwickeln. Das spanische Open-Source-Unternehmen Irontec will PHP auf Android-Smartphones bringen. Dazu hat es das ...
Read more

Bienvenue / Welkom — Irontec High Precision Tooling

Irontec High Precision Tooling ... Depuis plus de 20 ans IRONTEC SA est un acteur essentiel sur la scène du conseil technique et de la fourniture d ...
Read more

start [PHP for Android]

PHP for Android project (PFA) ... Irontec is the company behind this project. About this project. FAQ (Frequently Asked Questions) Phpforandroid en.
Read more

Open Ispilu | El espejo con información open data

Open Ispilu es un proyecto conjunto de Irontec y The Makery que transforma el espejo tradicional en una herramienta de señalización digital para ...
Read more

Ansprechpartner

Email: info(at)irontec.be WWW: www.irontec.be. Stefanie Nill Innendienst. Tel: +49 7022/408122 Fax: +49 7022/408208 Email: Stefanie.Nill(at)wohlhaupter.de ...
Read more