HTML Theming

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

Builders

Por fazer

Preencher quando o documento ‘construtores’ é dividido.

Themes

Novo na versão 0.6.

Nota

This section provides information about using pre-existing HTML themes. If you wish to create your own theme, refer to HTML theme development.

O Sphinx suporta a alteração da aparência de sua saída HTML através do themes. Um tema é uma coleção de templates 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 destaque 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.conf 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. Esta 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"

For more information on the design of themes, including information about writing your own themes, refer to HTML theme development.

Temas Builtins

Visão geral sobre Theme

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.

Note that from these themes only the Alabaster and Scrolls themes are mobile-optimated, the other themes resort to horizontal scrolling if the screen is too narrow.

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): Allow navigating with the following keyboard shortcuts:

    • Left arrow: previous page

    • Right arrow: next page

    O padrão é False.

  • enable_search_shortcuts (true or false): Allow jumping to the search box with / and allow removal of search highlighting with Esc.

    Defaults to True.

  • globaltoc_collapse (true or false): Only expand subsections of the current document in globaltoc.html (see html_sidebars). Defaults to True.

    Novo na versão 3.1.

  • globaltoc_includehidden (true or false): Show even those subsections in globaltoc.html (see html_sidebars) which have been included with the :hidden: flag of the toctree directive. Defaults to False.

    Novo na versão 3.1.

  • globaltoc_maxdepth (int): The maximum depth of the toctree in globaltoc.html (see html_sidebars). Set it to -1 to allow unlimited depth. Defaults to the max depth selected in the toctree directive.

    Novo na versão 3.2.

alabaster

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

classic

Este é o tema clássico, que se parece com the Python 2 documentation. 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

A more lightweight theme, based on the Jinja documentation. The following color options are available:

  • 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 (true or false): Put the sidebar on the right side. Defaults to 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 ou 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.

Novo 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

There are many third-party themes created for Sphinx. Some of these are for general use, while others are specific to an individual project.

sphinx-themes.org is a gallery that showcases various themes for Sphinx, with demo documentation rendered under each theme. Themes can also be found on PyPI (using the classifier Framework :: Sphinx :: Theme), GitHub and GitLab.