Introduccion

Esta es la documentación para el generador de documentación de Sphinx. Sphinx es una herramienta que traduce un conjunto de archivos de código fuente de reStructuredText en varios formatos de salida, produciendo automáticamente las referencias cruzadas, índices, etc. Es decir, si usted tiene un directorio que contiene un montón de documentos con formato reST (y posiblemente subdirectorios de documentación en allí tambien), Sphinx puede generar una disposición bien organizada de archivos HTML (en algún otro directorio) para fácil navegación. Pero de la misma fuente, también puede generar un fichero LaTeX que se puede compilar en una versión PDF de los documentos, o un PDF archivo directamente usando rst2pdf.

La atención se centra en la documentación escrita a mano, en lugar de documentación de la API generadas automáticamente. Aunque existe apoyo para ese tipo de documentos, así (que está destinada a ser mezclados libremente con el contenido escrito a mano), si usted necesita documentación de la API pura echar un vistazo a Epydoc, que también entiende reST.

Para una gran “introducción” a escribir documentos en general – los porqués y los cómos, vea también Write the docs, escrito por Eric Holscher.

Conversión desde otros sistemas

Esta sección está pensada para recoger consejos útiles para aquellos que quieran migrar a reStructuredText/Sphinx de otros sistemas de documentación.

  • Gerard Flanagan ha escrito un script para convertir HTML puro a reST; este se puede encontrar en el Python Package Index.
  • Para la conversión de los antiguos documentos de Python a Sphinx, un convertidor fue escrito, que se puede encontrar en el repositorio SVN Python. Contiene código genérico para convertir formato LaTeX estilo Python-doc a Sphinx reST.
  • Marcin Wojdyr ha escrito un script para convertir Docbook a reST con el marcado de Sphinx; este esta en Google Code.
  • Christophe de Vienne escribió una herramienta para convertir desde documentos de Open/LibreOffice a Sphinx: odt2sphinx.
  • Para convertir a diferentes markups, Pandoc es una herramienta muy útil.

Usar con otros sistemas

Ver la seccion pertinente en la lista de FAQ.

Requisitos previos

Sphinx needs at least Python 2.7 or Python 3.4 to run, as well as the docutils and Jinja2 libraries. Sphinx should work with docutils version 0.10 or some (not broken) SVN trunk snapshot. If you like to have source code highlighting support, you must also install the Pygments library.

Uso

Ver: doc:tutorial para una introducción. También contiene enlaces a secciones más avanzadas de este manual para los temas que aborda.