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 :

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
from pathlib import Path

sys.path.append(str(Path('exts').resolve()))

extensions = ['foo']

Também pode instalar extensões em qualquer outro lugar do sys.path, ex.. diretórios site-packages.