HTML theming

O Sphinx fornece vários construtores em HTML e formatos baseados em HTML.

Construtores

Temas

Adicionado na versão 0.6.

Nota

Esta seção fornece informações sobre o uso de temas HTML preexistentes. Se você deseja criar seu próprio tema, consulte Desenvolvimento de tema HTML.

O Sphinx tem suporte à alteração da aparência de sua saída HTML através do temas. Um tema é uma coleção de modelos HTML, folhas de estilo e outros arquivos estáticos. Além disso, ele possui um arquivo de configuração que especifica de qual tema herdar, qual estilo de realce usar e quais opções existem para personalizar a aparência do tema.

Temas são independentes de projetos e podem ser usados em diversos projetos em modificação.

Usando um tema

Usando um theme provided with Sphinx é fácil. Como estes não precisam ser instalados, você só precisa definir o valor de configuração html_theme. Por exemplo, para ativar o tema classic, adicione o seguinte ao conf.py:

html_theme = "classic"

Você também pode definir opções específicas do tema usando o valor de configuração html_theme_options. Essas opções geralmente são usadas para alterar a aparência do tema. Por exemplo, para colocar a barra lateral no lado direito e um plano de fundo preto para a barra de relações (a barra com os links de navegação na parte superior e inferior da página), adicione o seguinte conf.py:

html_theme_options = {
    "rightsidebar": "true",
    "relbarbgcolor": "black"
}

Se o tema não vem com o Sphinx, ele pode estar em dois formatos estáticos ou como um pacote Python. Para os formatos estáticos, um diretório (contendo theme.toml e outros arquivos necessários), ou um arquivo zip com o mesmo conteúdo, é suportado. O diretório ou zipfile deve ser colocado onde o Sphinx possa encontrá-lo; para isto, existe o valor de configuração html_theme_path. Este pode ser uma lista de diretórios, relativa ao diretório que contém conf.py, que pode conter diretórios de temas ou arquivos zip. Por exemplo, se você tem um tema no arquivo blue.zip, você pode colocá-lo no diretório que contém conf.py e usar esta configuração:

html_theme = "blue"
html_theme_path = ["."]

A terceira forma é um pacote Python. Se um tema que você deseja usar for distribuído como um pacote Python, você poderá usá-lo após a instalação

# installing theme package
$ pip install sphinxjp.themes.dotted

Uma vez instalado, isso pode ser usado da mesma maneira que um tema baseado em diretório ou zipfile:

html_theme = "dotted"

Para obter mais informações sobre o design de temas, incluindo informações sobre como escrever seus próprios temas, consulte Desenvolvimento de tema HTML.

Temas embutidos

Visão geral dos temas

alabaster

alabaster

classic

classic

sphinxdoc

sphinxdoc

scrolls

scrolls

agogo

agogo

traditional

traditional

nature

nature

haiku

haiku

pyramid

pyramid

bizstyle

bizstyle

O Sphinx vem com uma seleção de temas para escolher.

Observe que desses temas apenas os temas Alabaster e Scrolls são otimizados para dispositivos móveis, os demais temas recorrem à rolagem horizontal se a tela for muito estreita.

Esses temas são:

basico

Este é um layout basicamente não estilizado usado como base para os outros temas e utilizável como base para temas personalizados também. O HTML contém todos os elementos importantes, como barra lateral e barra de relação. Existem estas opções (que são herdadas pelos outros temas):

  • nosidebar (true ou false): não inclua a barra lateral. O padrão é False.

  • sidebarwidth (int ou str): Largura da barra lateral em pixels. Isso pode ser um int, que é interpretado como pixels ou uma string de dimensão CSS válida, como ‘70em’ ou ‘50%’. O padrão é de 230 pixels.

  • body_min_width (int ou str): Largura mínima do corpo do documento. Isso pode ser um int, que é interpretado como pixels ou uma string de dimensão CSS válida, como ‘70em’ ou ‘50%’. Use 0 se você não quiser um limite de largura. Os padrões podem depender do tema (geralmente 450px).

  • body_max_width (int ou str): Largura máxima do corpo do documento. Isso pode ser um int, que é interpretado como pixels ou uma string de dimensão CSS válida, como ‘70em’ ou ‘50%’. Use ‘none’ se você não quiser um limite de largura. Os padrões podem depender do tema (geralmente 800px).

  • navigation_with_keys (true or false): Permite navegar com os seguintes atalhos de teclado:

    • Left arrow: página anterior

    • Right arrow: página seguinte

    O padrão é False.

  • enable_search_shortcuts (true or false): Permite pular para a caixa de pesquisa com / e permite a remoção do realce de pesquisa com Esc.

    O padrão é True.

  • globaltoc_collapse (true ou false): Expande apenas subseções do documento atual em globaltoc.html (veja html_sidebars). O padrão é True.

    Adicionado na versão 3.1.

  • globaltoc_includehidden (true or false): Mostra até mesmo aquelas subseções em globaltoc.html (veja html_sidebars) que foram incluídas com o sinalizador :hidden: da diretiva toctree. O padrão é False.

    Adicionado na versão 3.1.

  • globaltoc_maxdepth (int): A profundidade máxima da toctree em globaltoc.html (veja html_sidebars). Defina-o como -1 para permitir profundidade ilimitada. O padrão é a profundidade máxima selecionada na diretiva toctree.

    Adicionado na versão 3.2.

alabaster

O tema Alabaster é um tema “Kr” modificado de @kennethreitz (especialmente usado em seu projeto Requests) para o Sphinx, que originalmente era baseado no tema de @mitsuhiko usado para o Flask e projetos relacionados. Consulte sua páginas de instalação para obter informações sobre como configurar html_sidebars para seu uso.

classic

Este é o tema clássico, que se parece com a documentação do Python 2. Pode ser personalizado através destas opções:

  • rightsidebar (True ou False): coloque a barra lateral no lado direito. O padrão é False.

  • stickysidebar (True ou False): Torna a barra lateral fixa para que não saia do campo de visão para o conteúdo do corpo longo. Isso pode não funcionar bem com todos os navegadores. O padrão é False.

  • collapsiblesidebar (True ou False): Adicione um snippet JavaScript experimental que torna a barra lateral recolhível por meio de um botão ao lado. O padrão é False.

  • externalrefs (True ou False): exibe links externos de maneira diferente dos links internos. O padrão é False.

Há também várias opções de cor e fonte que podem alterar o esquema de cores sem precisar escrever uma folha de estilo personalizada:

  • footerbgcolor (cor CSS): cor de fundo para a linha de rodapé.

  • footertextcolor (cor CSS): cor do texto para a linha de rodapé.

  • sidebarbgcolor (cor CSS): cor de fundo para a barra lateral.

  • sidebarbtncolor (cor CSS): Cor de fundo para o botão de recolhimento da barra lateral (usado quando collapsiblesidebar é True).

  • sidebartextcolor (cor CSS): cor do texto para a barra lateral.

  • sidebarlinkcolor (cor CSS): cor do link para a barra lateral.

  • relbarbgcolor (cor CSS): cor de fundo para a barra de relação.

  • relbartextcolor (cor CSS): cor do texto para a barra de relação.

  • relbarlinkcolor (cor CSS): cor do link para a barra de relação.

  • bgcolor (cor CSS): Cor de fundo do corpo.

  • textcolor (cor CSS): cor do texto do corpo.

  • linkcolor (cor CSS): Cor do link do corpo.

  • visitedlinkcolor (cor CSS): cor do corpo para links visitados.

  • headbgcolor (cor CSS): cor de fundo para títulos.

  • headtextcolor (cor CSS): cor do texto para títulos.

  • headlinkcolor (cor CSS): cor do link para títulos.

  • codebgcolor (cor CSS): cor de fundo para blocos de código.

  • codetextcolor (cor CSS): Cor de texto padrão para blocos de código, se não for definido de maneira diferente pelo estilo de destaque.

  • bodyfont (CSS font-family): fonte para texto normal.

  • headfont (CSS font-family): fonte para títulos.

sphinxdoc

O tema originalmente usado por esta documentação. Possui uma barra lateral no lado direito. Atualmente não há opções além de nosidebar e sidebarwidth.

Nota

A documentação do Sphinx agora usa an adjusted version of the sphinxdoc theme.

scrolls

Um tema mais leve, baseado na documentação do Jinja. As seguintes opções de cores estão disponíveis:

  • headerbordercolor

  • subheadlinecolor

  • linkcolor

  • visitedlinkcolor

  • admonitioncolor

agogo

Um tema criado por Andi Albrecht. As seguintes opções são suportadas:

  • bodyfont (família de fontes CSS): fonte para texto normal.

  • headerfont (família de fontes CSS): fonte para títulos.

  • pagewidth (comprimento CSS): Largura do conteúdo da página, padrão 70em.

  • documentwidth (comprimento CSS): Largura do documento (sem barra lateral), padrão 50em.

  • sidebarwidth (comprimento CSS): Largura da barra lateral, padrão 20em.

  • rightsidebar ( ou False): coloque a barra lateral no lado direito. O padrão é True.

  • bgcolor (cor CSS): cor de fundo.

  • headerbg (valor CSS para “background”): background para a área do cabeçalho, padrão um gradiente acinzentado.

  • footerbg (valor de CSS para “fundo”): plano de fundo para a área de rodapé, padrão um gradiente cinza claro.

  • linkcolor (cor CSS): Cor do link do corpo.

  • headercolor1, headercolor2 (cor CSS): cores para os cabeçalhos <h1> e <h2>.

  • headerlinkcolor (cor CSS): cor para o link de referência anterior nos títulos.

  • textalign (valor CSS text-align): Alinhamento de texto para o corpo, o padrão é justify.

nature

Um tema esverdeado. Atualmente não há opções além de nosidebar e sidebarwidth.

pyramid

Um tema do projeto de framework web Pyramid, projetado por Blaise Laflamme. Atualmente não há opções além de nosidebar e sidebarwidth.

haiku

Um tema sem barra lateral inspirada no Haiku OS user guide. As seguintes opções são suportadas:

  • full_logo (True ou False, padrão False): Se isso for True, o cabeçalho mostrará apenas o html_logo. Use isso para logotipos grandes. Se isso for falso, o logotipo (se presente) será exibido flutuando para a direita e o título da documentação será colocado no cabeçalho.

  • textcolor, headingcolor, linkcolor, visitedlinkcolor, hoverlinkcolor (cores CSS): cores para vários elementos do corpo.

traditional

Um tema parecido com a documentação antiga do Python. Atualmente não há opções além de nosidebar e sidebarwidth.

epub

Um tema para o construtor de EPUB. Este tema tenta salvar o espaço visual, que é um recurso escasso nos leitores de e-books. As seguintes opções são suportadas:

  • relbar1 (true ou false, padrão True): Se isso for verdade, o bloco relbar1 é inserido na saída epub, caso contrário, ele é omitido.

  • footer (true or false, padrão True): Se isto for True, o bloco footer é inserido na saída epub, caso contrário, ele é omitido.

bizstyle

Um simples tema azulado. As seguintes opções são suportadas além de nosidebar e sidebarwidth:

  • rightsidebar (True ou False): coloque a barra lateral no lado direito. O padrão é False.

Adicionado na versão 1.3: alabaster, sphinx_rtd_theme e bizstyle.

Alterado na versão 1.3: O tema padrão foi renomeado para classic, default ainda está disponível, no entanto, ele emitirá um aviso de que é um alias para o novo tema alabastro.

Temas de terceiros

Existem muitos temas de terceiros criados para o Sphinx. Alguns deles são para uso geral, enquanto outros são específicos para um projeto individual.

sphinx-themes.org é uma galeria que apresenta vários temas para o Sphinx, com documentação de demonstração renderizada para cada tema. Os temas também podem ser encontrados no PyPI (usando o classificador Framework :: Sphinx :: Theme), GitHub e GitLab.