Comenzando con python-sphinx

Instalación o Configuración #

Dado que Sphinx está disponible en el Python Package Index, se puede instalar usando pip:

pip install Sphinx

o también puede instalar usando easy_install

easy_install -U sphinx

Luego puedes comprobar que se ha instalado correctamente ejecutando el siguiente comando:

> sphinx-quickstart --version
Sphinx v1.4.1

Antes de continuar, debe seguir cierto estilo de código para python [PEP 8] 4. Si ha seguido la guía PEP 8, entonces puede definir la estructura del documento en sphinx y comenzar a construir su documentación.

Inicio rápido #

Para comenzar, vaya a la raíz del directorio del proyecto y ejecute:

$ sphinx-quickstart

Obtendrá opciones para crear documentación para su proyecto. Para la configuración predeterminada, siga los siguientes comandos:

Prompt    Choice
> Root path for the documentation [.]:    <ENTER>
> Separate source and build directories (y/N) [n]:    y
> Name prefix for templates and static dir [_]:    <ENTER>
> Project name:    an_example_pypi_project
> Author name(s):    Andrew Carter
> Project version:    0.0.1
> Project release [0.0.1]:    <ENTER>
> Source file suffix [.rst]:    <ENTER>
> Name of your master document (without suffix) [index]:    <ENTER>
> autodoc: automatically insert docstrings from modules (y/N) [n]:    y
> doctest: automatically test code snippets in doctest blocks (y/N) [n]:    n
> intersphinx: link between Sphinx documentation of different projects (y/N) [n]:    y
> todo: write “todo” entries that can be shown or hidden on build (y/N) [n]:    n
> coverage: checks for documentation coverage (y/N) [n]:    n
> pngmath: include math, rendered as PNG images (y/N) [n]:    n
> jsmath: include math, rendered in the browser by JSMath (y/N) [n]:    n
> ifconfig: conditional inclusion of content based on config values (y/N) [n]:    y
> Create Makefile? (Y/n) [y]:    n
> Create Windows command file? (Y/n) [y]:    n

Tras una ejecución exitosa, puede descubrir el archivo config.py en su directorio doc/source de su proyecto. Este archivo tiene control sobre la estructura básica de cómo se generará su documento cuando ejecute el comando de compilación como se muestra a continuación

$ sphinx-build -b html sourcedir builddir

Las instrucciones detalladas están disponibles en: https://pythonhosted.org/an_example_pypi_project/sphinx.html