Extensões¶
Diversos projetos necessitam funcionalidades especiais em sua documentação, O Sphinx permite adicionar “extensões” ao processo de construção da documentação e cada qual pode modificar aspectos individualizados no processamento.
Este capítulo descreve as extensões incluídas no Sphinx
. Para a documentação da API sobre como escrever sua própria extensão, consulte o Sphinx Extensions API.
Extensões internas¶
Essas extensões são construidas e pode ser ativadas através das respectivas entradas e valores na configuração extensions
:
sphinx.ext.autodoc
- Inclui documentação das docstringssphinx.ext.autosectionlabel
– Permite referenciar seção usando seu títulosphinx.ext.autosummary
– Gera resumos autodocsphinx.ext.coverage
– Coleta estatísticas docsphinx.ext.doctest
– Trechos de teste na documentaçãosphinx.ext.duration
– Mede durações de processamento Sphinxsphinx.ext.extlinks
– Marcação para encurtar links externossphinx.ext.githubpages
– Publicar docs HTML em páginas GitHubsphinx.ext.graphviz
– Adiciona Gráficos Graphvizsphinx.ext.ifconfig
– Inclui conteúdo baseado em configuraçãosphinx.ext.imgconverter
– Um conversor de imagem de referência usando o Imagemagicksphinx.ext.inheritance_diagram
– Incluir diagramas de herançasphinx.ext.intersphinx
– Link para documentação outros projetossphinx.ext.linkcode
- Adiciona links externos ao código-fonte- Suporte matemático para saídas HTML no
Sphinx
sphinx.ext.napoleon
– Suporte para doctrings de estilo NumPy e Googlesphinx.ext.todo
– Suporta itens todosphinx.ext.viewcode
– Adiciona links ao código destacado
Extensões Terceiros¶
You can find several extensions contributed by users in the sphinx-contrib organization. If you wish to include your extension in this organization, simply follow the instructions provided in the github-administration project. This is optional and there are several extensions hosted elsewhere. The awesome-sphinxdoc and sphinx-extensions projects are both curated lists of Sphinx packages, and many packages use the Framework :: Sphinx :: Extension and Framework :: Sphinx :: Theme trove classifiers for Sphinx extensions and themes, respectively.
Onde colocar suas próprias extensões?¶
Extensões locais para um projeto devem ser colocadas dentro da estrutura de diretório do projeto. Defina o path de pesquisa do módulo do Python, sys.path
, de forma que o Sphinx
possa localizá-los. Por exemplo, se sua extensão foo.py
estiver no subdiretório exts
da raiz do projeto, coloque em conf.py
:
import sys, os
sys.path.append(os.path.abspath('exts'))
extensions = ['foo']
Também pode instalar extensões em qualquer outro lugar do sys.path
, ex.. diretórios site-packages
.