jump to navigation

Suporte a Temas em HTML (CSS) 2011/02/01

Posted by gsavix in biblioteca pública wireless, classes de documentação web html, colaboração na aquisição conhecimento, como gerar documentos a partir dos programas fonte, como publicar na internet gratuitamente, Conhecimento, Conhecimento para receber ou transferir tecnologia, construtores de documentação, Doc, língua portuguesa, Memorando, metodologia para receber ou transferir conhecimento, notícias interesse público, publicação jornal internet, publicador documentação, Sistemas Computacionais, sociologia do conhecimento, Soft.
trackback

Suporte a Temas em HTML

Novo na versão 0.6.

Sphinx suporta a mudança na aparência dos HTML gerados, através da funcionalidade chamada tema. Tema é uma coleção de modelos de folhas de estilo (CSS) além de outros tipos de arquivos estáticos. Adicionalmente, pode haver a configuração de arquivos que podem ter seu tema herdado de outro tema, permitindo utilizar várias opções de aparência e comportamento.

Temas podem ser desvinculados de projetos, podendo ser utilizados de maneira diferente em cada um deles, sem sofrer mudanças.

Usando um tema

Usar um tema existente é fácil. Se o tema já veio com o Sphinx, você só precisa configurar html_theme para o valor desejado.Com valor de html_theme_options você escolhe opções de aparência e comportamento. Por exemplo, você pode ter o seguinte em seu arquivo conf.py:

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

Isto irá dar a você o tema padrão, mas com uma barra lateral à direita e uma barra de relação ( a barra de navegação das ligações no topo e no rodapé) na cor preta.

Se o tema não veio com o Sphinx, ele pode ser em duas formas: um diretório contendo o arquivo theme.conf e outros arquivos necessários, ou um arquivo zip com os mesmos conteúdos. Qualquer um deles pode ser colocado onde o Sphinx pode encontrá-los; para isso pode ser usado o valor de configuração html_theme_path. Ele dá uma lista de diretórios, relativos ao diretório contendo o arquivo conf.py, os quais podem conter temas ou arquivos zip. Por exemplo, se você tem um tema em um arquivo blue.zip, você pode colocá-lo no arquivo conf.py e usar esta configuração:

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

Temas Internos

Visão Temas
default 

default

sphinxdoc 

sphinxdoc

scrolls 

scrolls

agogo 

agogo

traditional 

traditional

nature 

nature

haiku 

haiku

O Sphinx vem com uma seleção de temas que você pode usar.

Estes temas são:

  • basic – Essa é a formatação sem estilo usada como base para outros temas, e utilizável como base para outros temas configuráveis também. O HTML contém todos os elementos importantes como barras laterais e barras de relação. Tem uma opção (a qual é herdada por outros temas):
    • nosidebar (verdadeiro ou falso): Não inclui a barra lateral. Padrão é falso.
  • default – Este é o tema padrão,o qual parece com Documentação Python em <http://docs.python.org/>`_. Pode ser personalizado através destas opções:
    • rightsidebar (verdadeiro ou falso): Barra lateral do lado direito. Padrão é Falso.
    • stickysidebar (verdadeiro ou falso): Barra lateral ser fixa, ela não rola para fora da visão para conteúdos longos. Isto pode não funcionar bem para todos os navegadores. Padrão é falso.
    • collapsiblesidebar (true or false): Add an experimental JavaScript snippet that makes the sidebar collapsible via a button on its side. Doesn’t work together with “rightsidebar” or “stickysidebar”. Defaults to false.
    • externalrefs (true or false): Display external links differently from internal links. Defaults to false.

    There are also various color and font options that can change the color scheme without having to write a custom stylesheet:

    • footerbgcolor (CSS color): Background color for the footer line.
    • footertextcolor (CSS color): Text color for the footer line.
    • sidebarbgcolor (CSS color): Background color for the sidebar.
    • sidebarbtncolor (CSS color): Background color for the sidebar collapse button (used when collapsiblesidebar is true).
    • sidebartextcolor (CSS color): Text color for the sidebar.
    • sidebarlinkcolor (CSS color): Link color for the sidebar.
    • relbarbgcolor (CSS color): Background color for the relation bar.
    • relbartextcolor (CSS color): Text color for the relation bar.
    • relbarlinkcolor (CSS color): Link color for the relation bar.
    • bgcolor (CSS color): Body background color.
    • textcolor (CSS color): Body text color.
    • linkcolor (CSS color): Body link color.
    • visitedlinkcolor (CSS color): Body color for visited links.
    • headbgcolor (CSS color): Background color for headings.
    • headtextcolor (CSS color): Text color for headings.
    • headlinkcolor (CSS color): Link color for headings.
    • codebgcolor (CSS color): Background color for code blocks.
    • codetextcolor (CSS color): Default text color for code blocks, if not set differently by the highlighting style.
    • bodyfont (CSS font-family): Font for normal text.
    • headfont (CSS font-family): Font for headings.
  • sphinxdoc – The theme used for this documentation. It features a sidebar on the right side. There are currently no options beyond nosidebar.
  • scrolls – A more lightweight theme, based on the Jinja documentation. The following color options are available:
    • headerbordercolor
    • subheadlinecolor
    • linkcolor
    • visitedlinkcolor
    • admonitioncolor
  • agogo – A theme created by Andi Albrecht. The following options are supported:
    • bodyfont (CSS font family): Font for normal text.
    • headerfont (CSS font family): Font for headings.
    • pagewidth (CSS length): Width of the page content, default 70em.
    • documentwidth (CSS length): Width of the document (without sidebar), default 50em.
    • sidebarwidth (CSS length): Width of the sidebar, default 20em.
    • bgcolor (CSS color): Background color.
    • headerbg (CSS value for “background”): background for the header area, default a grayish gradient.
    • footerbg (CSS value for “background”): background for the footer area, default a light gray gradient.
    • linkcolor (CSS color): Body link color.
    • headercolor1, headercolor2 (CSS color): colors for <h1> and <h2> headings.
    • headerlinkcolor (CSS color): Color for the backreference link in headings.
    • textalign (CSS text-align value): Text alignment for the body, default is justify.
  • nature – A greenish theme. There are currently no options beyond nosidebar.
  • haiku – A theme without sidebar inspired by the Haiku OS user guide. The following options are supported:
    • full_logo (true or false, default false): If this is true, the header will only show the html_logo. Use this for large logos. If this is false, the logo (if present) will be shown floating right, and the documentation title will be put in the header.
    • textcolor, headingcolor, linkcolor, visitedlinkcolor, hoverlinkcolor (CSS colors): Colors for various body elements.
  • traditional – A theme resembling the old Python documentation. There are currently no options beyond nosidebar.
  • epub – A theme for the epub builder. There are currently no options. This theme tries to save visual space which is a sparse resource on ebook readers.

Criando temas

Como foi dito, temas podem ser diretórios ou arquivos zip (cujo nome é o nome tema), contendo o seguinte:

  • Um arquivo theme.conf veja abaixo,
  • Modelos HTML, se necessário.
  • Um diretório static/ contento qualquer arquivos estáticos, que serão copiados para o diretório estático de saída (diretório de build). Podem ser imagens, folhas de estilo, scripts, etc.

O arquivo theme.conf tem formato de INI [1] (legível inclusive pelo módulo Python ConfigParser) e tem a seguinte estrutura:

[theme]
inherit = base theme
stylesheet = main CSS name
pygments_style = stylename

[options]
variable = default value
  • inherit fornece o nome do tema básico “base theme”, ou none. O tema básico irá ser usado para localizar modelos inexistentes ( muitos temas não conseguem suprir outros modelos se eles usam basic como tema básico), estas opções serão herdadas e todos seus arquivos estáticos também.
  • stylesheet fornece o nome do arquivo CSS que será referenciado no header do HTML gerado. Se você preceisa mais de um CSS, inclua o segundo a partir do primeiro usando CSS’ @import, ou utilize um modelo de HTML que adiciona a ligação <link rel="stylesheet"> e as tags necessárias. Configurando o valor html_style irá sobrepor esta configuração.
  • pygments_style fornece o nome do estilo de “Pygments” que deverá ser usado para enfatizar as cores. Configurando o valor pygments_style irá sobrepor esta configuração.
  • A seção options contém pares de nome de variáveis e valores. Estas opções podem ser sobrepostas pelo usuário através de html_theme_options e são acessíveis a partir de todos os modelos como theme_<name>.

Modelos

O guia para modelos css guide to templating ajuda se você deseja escrever seu próprio modelo. O que é importante ter em mente é a ordem na qual o Sphinx procura por modelos (templates):

  • Primeiro, nos diretórios modelos do usuário templates_path.
  • Depois, no tema selecionado.
  • Após, em seus temas internos, Sphinx tema básico, etc.

Quando estender um modelo de tema, com o mesmo nome, use o nome do tema como um nome de diretório explícito: {% extends "basic/layout.html" %}. A partir de um modelo de usuário templates_path, você pode usar o “ponto de exclamação” como na sintaxe descrita no documento de modelo.

Modelos Estáticos

Temas foram criados para facilitar, o usuário em configurar aparência da documentação sem precisar escrever uma folha de estilos. É necessário um tema modelo bem como arquivos HTML. Entretanto o Sphinx suporta o que é chamado de “modelos estáticos” como segue:

Se o nome do arquivo está em um diretório de temas static/ ou em um caminho estático (terminado por _t), irá ser processado pelo motor de modelos. O _t irá ser deixado no final do nome do arquivo. Por ex: o tema padrão default é um arquivo static/default.css_t o qual usa um modelo para colocar cores em uma folha de estilo (css). Quando a documentação for construída com o tema padrão, o diretório de saída irá conter um arquivo _static/default.css onde os alvos (tags) já foram tratadas.

[1] Ele não é um arquivo Python executável, em oposição ao arquivo conf.py, pois pode expor a risco de segurança desnecessário já que é compartilhado.
Anúncios

Comentários»

No comments yet — be the first.

Deixe um comentário

Faça o login usando um destes métodos para comentar:

Logotipo do WordPress.com

Você está comentando utilizando sua conta WordPress.com. Sair / Alterar )

Imagem do Twitter

Você está comentando utilizando sua conta Twitter. Sair / Alterar )

Foto do Facebook

Você está comentando utilizando sua conta Facebook. Sair / Alterar )

Foto do Google+

Você está comentando utilizando sua conta Google+. Sair / Alterar )

Conectando a %s

%d blogueiros gostam disto: