jump to navigation

Contrutores disponíveis¶ 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 classe do documentos web, construtores de documentação, Doc, gerador documentos, Memorando, metodologia para receber ou transferir conhecimento, publicação jornal internet, publicador documentação, Sistemas Computacionais, sociologia do conhecimento.
trackback

Contrutores disponíveis

Estas são as classes de construtores internas do Sphinx. Mais construtores (Builders) podem ser adicionadas através extensões.

O nome do construtor precisa ser dado para a opção -b da linha de comando do sphinx-build para o construtor selecionado.

class sphinx.builders.html.StandaloneHTMLBuilder
Este é o construtor padrão de HTML. Sua saida é um diretório ou pasta com arquivos HTML, completados com folhas de estilos (CSS) e opcionalmente fontes de arquivos (reST). Existem poucos valores para escolher as opções desejadas neste construtor, veja o capítulo Opções para Saída HTML para detalhes.

Seu nome é html.

class sphinx.builders.html.DirectoryHTMLBuilder
Esta é uma subclasse do construtor HTML. Sua saida é um diretório contendo arquivos HTML, onde cada arquivo é chamado index.html e colocado em um subdiretório ou subpasta com nome igual ao do nome da página. Por exemplo: O documento markup/rest.rst não irá resultar em um arquivo markup/rest.html, mas markup/rest/index.html. Quando gerando ligações entre as páginas, o index.html é omitido, então aquela URL parecerá com markup/rest/.

Seu nome é dirhtml.

Novo na versão 0.6.

class sphinx.builders.html.SingleFileHTMLBuilder
Esse é um construtor HTML que combina todo o projeto em um único arquivo. (Obviamente isso só funciona para pequenos projetos.) O arquivo é nomeado como documento mestre. Não é gerado índice.

Seu nome é singlehtml.

Novo na versão 1.0.

class sphinx.builders.htmlhelp.HTMLHelpBuilder
Esse construtor produz a mesma saída que o construtor HTML, mas também cria arquivos de suporte Help HTML, que permitem que o Microsoft HTML Help Workshop, compile-os em um arquivo (CHM).

Seu nome é htmlhelp.

class sphinx.builders.qthelp.QtHelpBuilder
Esse construtor produz a mesma saída que o construtor HTML, mas também cria uma coleção de arquivos de suporte Qt help que permitem ao gerador de coleção Qt compilá-los.

Seu nome é qthelp.

class sphinx.builders.devhelp.DevhelpBuilder
Esse construtor produz a mesma saída padrão HTML, mas também cria GNOME Devhelp suporte arquivo que permite ao leitor GNOME Devhelp enxergá-los.

Seu nome é devhelp.

class sphinx.builders.epub.EpubBuilder
Esse construtor produz a mesma saída que o construtor HTML, mas também cria um arquivo epub para leitores de ebook. Veja Epub info para detalhes sobre ele. Para o formato das definições de epub olhe em http://www.idpf.org/specs.htm ou http://en.wikipedia.org/wiki/EPUB.

Alguns leitoros ebook não exibem os alvos das ligações de referência, entretanto este construtor adiciona os alvos, após as ligações quando necessário. A exibição de URLs pode ser personalizada através de regras CSS para a classe link-target.

Seu nome é epub.

class sphinx.builders.latex.LaTeXBuilder
Esse construtor produz um conjunto de arquivos LaTeX em um diretório de saída. Você deve especificar quais documentos serão incluídos nos arquivos LaTeX através do valor latex_documents. Existem alguns valores que podem ser personalizados para esse construtor, veja o capítulo Options for LaTeX output para mais detalhes.

Nota

A produção de arquivo LaTeX utiliza vários pacotes LaTeX que podem não estarem presentes em uma distribuição “mínima”. Para TeXLive, os seguintes pacotes precisam estar instalados:

  • latex-recommended
  • latex-extra
  • fonts-recommended

Seu nome é latex.

Note que um construtor direto PDF usando ReportLab está disponível em rst2pdf versão 0.12 ou maior. Pode ser necessário adicionar 'rst2pdf.pdfbuilder' para seu extensions para habilitá-lo, seu nome é pdf. Veja o manual rst2pdf manual para detalhes.

class sphinx.builders.text.TextBuilder
Esse construtor produz um arquivo de texto para cada arquivo reST – isto é o mesmo que a fonte reST, porém com várias marcações eliminadas para melhor legibilidade.

Seu nome é text.

Novo na versão 0.4.

class sphinx.builders.manpage.ManualPageBuilder
Esse construtor produz páginas de manual no formato groff. Você precisa especificar quais documentos serão incluídos nas páginas do manual através do valor de configuração man_pages.

Seu nome é man.

Nota

Esse construtor requer o gerador de páginas man docutils, e está disponível na versão 0.6 do docutils.

Novo na versão 1.0.

class sphinx.builders.html.SerializingHTMLBuilder
Esse construtor usa um módulo que implementa a API de serialização Python (pickle, simplejson, phpserialize e outras) para dar saída a documanetação gerada. O construtor pickle é uma subclasse dele.

Uma subclasse concreta desse construtor de serialização é a PHP serialization cujo formato é esse:

import phpserialize

class PHPSerializedBuilder(SerializingHTMLBuilder):
    name = 'phpserialized'
    implementation = phpserialize
    out_suffix = '.file.phpdump'
    globalcontext_filename = 'globalcontext.phpdump'
    searchindex_filename = 'searchindex.phpdump'
implementation
Um módulo que implementa funções dump(), load(), dumps() e loads() que tem os mesmos nomes conforme o módulo pickle. Módulos conhecidos na implementação desse interface são`simplejson` (ou json em Python 2.6), phpserialize, plistlib e outros.

out_suffix
O sufixo para arquivos normais.

globalcontext_filename
O nome de arquivo que contém “contexto global”. Esse é um dict (dicionário) contendo valores das configurações gerais, como por exemplo o nome do projeto.

searchindex_filename
O nome do arquivo para pesquisa do índice, que será gerado pelo Sphinx.

Veja Detalhes sobre Construtores de Serialização para detalhes sobre o formato da saída.

Novo na versão 0.5.

class sphinx.builders.html.PickleHTMLBuilder
Esse construtor produz um diretório ou pasta contendo arquivos pickle contendo fragmentos de HTML e informação sobre (TOC tabela de conteúdo), para uso com uma aplicação web ou ferramento para pós-processamento, a qual não usa os modelos de HTML padrão. Veja Detalhes sobre Construtores de Serialização para detalhes sobre o formato da saída.

Seu nome é pickle. (O nome antigo web também funciona.)

O sufixo de arquivo é .fpickle. O contexto global é chamado globalcontext.pickle, e o índice de pesquisa searchindex.pickle.

class sphinx.builders.html.JSONHTMLBuilder
Esse construtor produz um diretório com arquivos JSON, contendo fragmentos HTML e informações TOC, para uso em aplicação web (ou configurado para ferramentas de pósprocessamento) que não utiliza templates padrões HTML.

Veja Detalhes sobre Construtores de Serialização para detalhes sobre o formato da saída.

Seu nome é json.

O sufixo do arquivo é .fjson. O contexto global é chamado globalcontext.json, o índice searchindex.json.

Novo na versão 0.5.

class sphinx.builders.changes.ChangesBuilder
Esse construtor produz HTML com visão de todas as diretivas novidades da versão, versionadded e com as tornadas obsoletas deprecated na versão corrente version. Isto é utilizado para atualizar um arquivo registro de modificações “ChangeLog”, por exemplo.

Seu nome é: changes.

class sphinx.builders.linkcheck.CheckExternalLinksBuilder
Esse construtor procura em todos os documentos para ligações externas e tenta abrir, utilizando o módulo urllib2, e grava informações sobre quais estão quebradas para a saída padrão e para um arquivo chamado output.txt no diretório de saída.

Seu nome é linkcheck.

Extensões nativas (Built-in) do Sphinx que oferencem mais construtores são:

Detalhes sobre Construtores de Serialização

Todos os construtores de serialização gravam um arquivo para cada arquivo fonte e alguns arquivos especiais. Eles também copiam os arquivos fonte reST para o diretório ou pasta _sources sob o diretório ou pasta de saída.

A PickleHTMLBuilder é uma subclasse que implementa o interface de serialização.

Os arquivos do arquivo fonte têm a extensão out_suffix e são organizados em diretórios ou pastas assim como os arquivos fontes estão. Eles são revertidos para um dicionário (estrutura como um dicionário) com estas chaves:

body
O HTML “body” (isto é, o HTML deduzido do arquivo fonte), é renderizado pelo tradutor HTML.
title
O título do documento, como HTML (pode conter markup).
toc
A tabela de conteúdos do arquivo, é renderizada como um HTML <ul>.
display_toc
Um booleano que é True se o toc contém mais de uma entrada.
current_page_name
O nome do documento do arquivo corrente.
parents, prev and next
Informação sobre capítulos relacionados à árvore TOC. Cada relação é um dicionário com as chaves link (HREF para a relação) e title (título do documento relacionado, como HTML). parents é a lista das relações, enquanto prev e next são relações simples.
sourcename
O nome do arquivo fonte sob _sources.

Os arquivos especiais estão localizados no diretório ou pasta de saída. São:

SerializingHTMLBuilder.globalcontext_filename
Um dicionário pickled com as chaves:

project, copyright, release, version
Os mesmos valores informados no arquivo de configuração.
style
html_style.
last_updated
Data da última geração.
builder
Nome do construtor utilizado, no caso de pickles será sempre 'pickle'.
titles
Um dicionário de todos os documentos títulos como strings HTML.
SerializingHTMLBuilder.searchindex_filename
Um índice que pode ser usado para pesquisar na documentação. É uma lista pickled com as seguintes entradas:

  • Uma lista indexada de nomes de documentos.
  • Uma lista de títulos de documentos, como strings HTML, na mesma ordem da primeira lista.
  • Um dicionário mapeando palavras raízes (processadas por um stemmer em inglês) para uma lista de inteiros, os quais são índices para a primeira.
environment.pickle
O ambiente do construtor. Sempre é um arquivo pickle, independente do construtor e uma cópia do ambiente no qual o construtor foi iniciado.

Por fazer

Documentar os membros comuns.

Diferentemente de outros arquivos pickle, esse arquivo requer que o pacote sphinx esteja disponível para desfazer o pickle.

Anúncios

Comentários»

No comments yet — be the first.

Deixe uma resposta

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: