Mais personalização do Sphinx¶

Existem duas maneiras principais de personalizar sua documentação além do que é possível com o Sphinx base: extensões e temas.

Habilitando uma extensão embutida¶

Além desses valores de configuração, você pode personalizar ainda mais o Sphinx usando extensões. O Sphinx inclui várias extensões embutidas e há muitos mais mantidas pela comunidade.

Por exemplo, para habilitar a extensão sphinx.ext.duration, localize a lista extensions em seu conf.py e adicione um elemento como segue:

docs/source/conf.py¶

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
    'sphinx.ext.duration',
]

Depois disso, toda vez que você gerar sua documentação, você verá um relatório de durações curtas no final da saída do console, como este:

(.venv) $ make html
...
The HTML pages are in build/html.

====================== slowest reading durations =======================
0.042 temp/source/index

Usando um tema HTML de terceiros¶

Os temas, por outro lado, são uma forma de personalizar a aparência da sua documentação. O Sphinx tem vários temas embutidos e também existem temas de terceiros.

Por exemplo, para usar o tema de terceiros Furo em sua documentação HTML, primeiro você precisará instalá-lo com pip em seu ambiente virtual Python, assim:

(.venv) $ pip install furo

E então, localize a variável html_theme em seu conf.py e substitua seu valor da seguinte forma:

docs/source/conf.py¶

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
html_theme = 'furo'

Com esta mudança, você notará que sua documentação HTML agora está com uma nova aparência:

Documentação HTML do Lumache com o tema Furo¶

Agora é hora de expandir a documentação narrativa e dividi-la em vários documentos.