Sphinx

Faça uma documentação bonita e inteligente.

O que é?



Sphinx é uma ferramenta para criar uma documentação de maneira fácil, inteligente e bonita.

História


  • Escrito por Georg Brandl, e distribuido na licença BSD
  • Criado originalmente para a documentação do Python. E possui diversas facilidades para a linguagem.
  • Também suporta as linguagem C/C++

Caracteristicas


  • Utiliza o padrão  reStructuredText (.rst)
  • Formatos de saídas: HTML, LATEX, PDF, EPUB, textos simples e etc...
  • Possui marcação semântica e links automáticos para funções, classes, citações, termos do glossário.
  • Estrutura hierarquica, em árvore, para os documentos.
  • Índices automáticos dos modulos, extensões (pngmath, autodoc, doctest...) 

Como instalar?




 (learn_sphinx)➜  sphinx git:(master) ✗ pip install sphinx

Inicializando a doc


(learn_sphinx)➜  sphinx git:(inicializando_a_doc) mkdir docs 

(learn_sphinx)➜  sphinx git:(inicializando_a_doc) cd docs

(learn_sphinx)➜  docs git:(inicializando_a_doc) sphinx-quickstart





PASSO A PASSO

> Root path for the documentation [.]: <ENTER>> Separate source and build directories (y/N) [n]: y
> Name prefix for templates and static dir [_]:
> Project name: Learn Sphinx Documentation
> Author name(s): Lucas Simon Rodrigues Magalhaes
> Project version: 0.0.1
> Project release [0.0.1]:
> Source file suffix [.rst]:
> Name of your master document (without suffix) [index]:
> Do you want to use the epub builder (y/N) [n]: y
> autodoc: automatically insert docstrings from modules (y/N) [n]: y > doctest: automatically test code snippets in doctest blocks (y/N) [n]: y > intersphinx: link between Sphinx documentation of different projects (y/N) [n]: y > coverage: checks for documentation coverage (y/N) [n]: y > viewcode: include links to the source code of documented Python objects (y/N) [n]: y > Create Makefile? (Y/n) [y]: y > Create Windows command file? (Y/n) [y]: y

alterando o conf.py


Seta a codificação para utf-8
 source_encoding = 'utf-8-sig'
Seta a linguagem da documentação para PT-BR
 language = 'pt_br'
Caso queira alterar o layout padrão
 html_theme = 'default'

Colocando o django


sys.path.insert(0, os.path.abspath("../.."))
from unipath import Path

DJANGO_PROJECT_DIR = Path(__file__).ancestor(3)

SETTINGS_SPHINX = DJANGO_PROJECT_DIR.child('sphinx')
CORE_SPHINX = DJANGO_PROJECT_DIR.child('core').absolute()

sys.path.append(str(SETTINGS_SPHINX))


sys.path.append(str(CORE_SPHINX))
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "settings.base")




ComPILANDO PARA HTML

(learn_sphinx)➜  docs git:(inicializando_a_doc) ✗ make html




EXIBINDO NO BROWSER

(learn_sphinx)➜  docs git:(inicializando_a_doc) ✗ python -m SimpleHTTPServer 9000




Sistema marcacao de texto







A TOC TREE





Exemplo de documentacao




READTHEDOCS FTW






FIM

Sphinx

By Lucas Simon Rodrigues Magalhaes

Sphinx

Como criar uma boa documentação para seu projeto Django

  • 1,201