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 API do Sphinx.
Extensões embutidas¶
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 de cobertura da documentaçãosphinx.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– Inclui 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 de terceiros¶
Você pode encontrar várias extensões fornecidas por usuários na organização sphinx-contrib. Se você deseja incluir sua extensão nesta organização, simplesmente siga as instruções fornecidas no projeto github-administration. Isso é opcional e existem várias extensões hospedadas em outro lugar. Os projetos awesome-sphinxdoc e sphinx-extensions contêm lista com curadoria de pacotes Sphinx, e muitos pacotes usam os classificadores Framework :: Sphinx :: Extension e Framework :: Sphinx :: Theme para extensões e temas Sphinx, respectivamente.
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.