Documentar projetos Python com Sphinx

Postado por em

Introdução

Este artigo é um overview do sphinx, obtido por tradução livre do conteúdo original em docguide sphinx.

Para aprofundar o conhecimento sobre o assunto, poderá ser consultado os textos da referência.

Instalação

easy_install -U sphinx
ou
pip install -U sphinx

Inicialização rápida

Após iniciado, entre no diretório que será realizada a documentação e digite:
sphinx-quickstart
Abaixo uma sequência de respostas padrão para iniciar o projeto:
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
Ao termino da configuração terá uma saída como esta: 
Finished: An initial directory structure has been created.

You should now populate your master file .\source\index.rst and create other documentation
source files. Use the sphinx-build command to build the docs, like so:
   sphinx-build -b builder .\source .\build
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

conf.py

Agora em seu diretório doc/source tm um arquivo python chamado conf.py.

Este arquivo controla o funcionamento básico do sphinx e direciona a execução para o build.

Nele poderá ser configurado:

  • atulização do número de version/release por meio de configuração das variáveis;
  • Configuração do nome de projeto e autor;
  • Configuração do logo de projeto;
  • Configuração do layout de estrutura padrão para o projeto (por padrão é utilizado o python docs);
  • e outros recursos que poderão ser entendidos os recursos básicos através deste artigo.

reStructured Text (reST) Resources

Sphinx utiliza o recurso de reStructured text, e quando se utiliza do sphinx quase todo o texto digitado em reStructured text. Esclarecimentos sobre o assunto podem ser encontrados nos links abaixo:

Negrito/Italico

Negrito e italico são obtidos assim:
**bold** e *italics*

Listas

* A thing.
* Another thing.
ou
- Some.
- Thing.
- Different.
Resultado:
  • A thing.
  • Another thing.

  • Some.
  • Thing.
  • Different.
ou
1. Item 1.
2. Item 2.
3. Item 3.
Resultado:
  1. Item 1.
  2. Item 2.
  3. Item 3.

Headers

Sphinx permite convenção personalizada e cabe a você escolher uma convenção própria para cabeçalhos.

H1 -- Top of Page Header
************************
O header H1, deve ser utilizado para distinção de capitulos, apenas uma vez por página, inclusive para conversão em PDF.
H2 -- Page Sections
===================
H3 -- Subsection
----------------
H4 -- Subsubsection
+++++++++++++++++++

Um recomendado pela documentação de referência é este abaixo:

A Subpoint
----------
This is my idea.
A subsubpoint
+++++++++++++
This is a smaller idea.

Tables

As tabelas são criadas como demonstrado abaixo.

COMPLEX TABLE

+------------+------------+-----------+
| Header 1   | Header 2   | Header 3  |
+============+============+===========+
| body row 1 | column 2   | column 3  |
+------------+------------+-----------+
| body row 2 | Cells may span columns.|
+------------+------------+-----------+
| body row 3 | Cells may  | - Cells   |
+------------+ span rows. | - contain |
| body row 4 |            | - blocks. |
+------------+------------+-----------+

SIMPLE TABLE

=====  =====  ======
   Inputs     Output
------------  ------
  A      B    A or B
=====  =====  ======
False  False  False
True   False  True
False  True   True
True   True   True
=====  =====  ======
O restante das funcionalidades pode ser acompanhado na republicação com o idioma original em Brito: Documenting your project using sphinx.

Referências

Brito: Documenting Your Project Using Sphinx http://docs.geoserver.org/trunk/en/docguide/sphinx.html
https://pythonhosted.org/an_example_pypi_project/sphinx.html
http://sphinx.pocoo.org/

Comentários

Postar um comentário