python-sphinx Tutorial
Empezando con python-sphinx
Buscar..
Observaciones
Esta sección proporciona una descripción general de qué es python-sphinx y por qué un desarrollador puede querer usarlo.
También debe mencionar cualquier tema grande dentro de python-sphinx, y vincular a los temas relacionados. Dado que la Documentación para python-sphinx es nueva, es posible que deba crear versiones iniciales de esos temas relacionados.
Instalación o configuración
Como Sphinx está disponible en el Índice de Paquetes de Python , se puede instalar usando pip :
pip install Sphinx
o también puedes instalar usando easy_install
easy_install -U sphinx
Luego, puede verificar que se haya 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 . Si ha seguido las pautas de PEP 8 , puede definir la estructura del documento con esfinge y comenzar a crear su documentación .
Inicio rápido
Para comenzar vaya al directorio raíz 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 el directorio doc / source de su proyecto. Este archivo tiene el control de la estructura básica de cómo se generará su documento cuando ejecute el comando de compilación de la siguiente manera
$ sphinx-build -b html sourcedir builddir
Las instrucciones detalladas están disponibles en: https://pythonhosted.org/an_example_pypi_project/sphinx.html