jump to navigation

Três Pulinhos no Tablet Acer Iconia One 7 2015/06/06

Posted by gsavix in computador portátil, Computadores, debug android, dedução, Doc, Memorando, open source computer, organização do conhecimento, organização do raciocínio dedutivo, sistema hipotético dedutivo, Sistemas Computacionais.
Tags: , , , ,
add a comment

Se você também é mais um dos milhares de consumidores que comprou um tablet acer esses vendidos em “Baciada” olhou a caixinha e viu escrito intel inside olhou que é versão 4.4.2 LollyPop, viu que tem bluetooth, 8 gigabytes de memória e decidiu comprar o Acer B1-730.

Agora chegou em casa viu que assim como outros equipamentos essa galera da acer também instalou vários aplicativos úteis e vários inúteis, chegou a conclusão
que quer desintalar os inúteis, tentou desinstalar e não conseguiu.

Aí sentiu aquela sensação, “xi vou ter que engolir!”

Ah não! essa não! me disseram que o Android era um sistema operacional livre!

Após uma rápida pesquisa na internet descobriu que para excluir aplicações consideradas inúteis você precisa assumir poderes de super-usuário ou superusuário ou mesmo super usuário.

Descobriu que no linux normal você usa: sudo passwd e basta informar a nova senha do super user root.

Ah! simples! vamos nessa!

Pegou o cabo usb conectou na seu computador com o sistema operacional do bill gates e recebeu uma mensagem dizendo que seu equipamento foi reconhecido pelo windows e que você deve colocar o seu recém adquirido tablet android 4.4.2 no modo “usb debug” modo esse que pode ser encontrado dentro
do menu desenvolvedor.

Ora bolas! toda essa conversa para explicar que o menu do desenvolvedor fica oculto!

Putz! como acessar então? Simples! siga essas instruções gentilmente colocadas no site da acer do reino unido e você conseguira finalmente acessar o menu desenvolvedor para colocar a usb em modo debug!

Ah! façam-me o favor né! Não basta terem configurado meu tablet como idioma padrão francês ainda mais essa receitinha dos 7 tapinhas no menu “sobre meu tablet”

Enable Developer Options on Android 4.2 and later

How do I enter the Developer options menu on my Android tablet or phone running 4.2 or later?

The Developer options menu will give you access to USB debugging mode and other developer options.

Use the following steps to to gain access to the Developer options menu.

Go to Settings.
Scroll down and select the About tablet or About phone option.
Scroll down to the Build number and tap it seven times.
You will see a confirmation message and the Developer options menu will appear on the left.

Anúncios

publicar periódico ou jornal na web com htmldoc 2011/02/02

Posted by gsavix in classes de documentação web html, 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, Soft.
add a comment

Overview

Assim como outros programas  HTMLDOC  foi desenvolvido como resposta a uma necessidade de algumas organizações gerar documentação de alta qualidade, tanto impressas como na web.

Com a escrita do programa HTMLDOC para gerar documentação, naturalmente o HTML tornou-se a fonte de tudo, pois com a escolha de um editor o que você ve é o que você obtem “WYSIWYG” e em último caso você também pode usar um editor de texto para criar sua documentação.  Nós geramos HTML como saída em nossa documentação, que pode ser vista em um web server. Também pode ser gerada a saída em arquivo formato PDF ou PostScript para atender a qualquer requerimento de visualização ou impressão.

O resultado do nosso esforço é que HTMLDOC está disponível em Linux®/UNIX®, GNU/Linux, MacOS® X, and Microsoft® Windows®. Este manual foi produzido utilizando HTMLDOC, e esta tradução foi feita a partir do site http://www.htmldoc.org. Enquanto HTMLDOC pode converter páginas web em arquivos PostScript ou PDF, seu forte é gerar publicações indexadas.

HTMLDOC usa elementos de cabeçalho HTML para delinear capítulos e cabeçalhos nas publicações. O elemento  H1 é usado para capítulos:

    <HTML>
    <HEAD>
	<TITLE>O pequeno computador que pode</TITLE>
    </HEAD>
    <BODY>
    <H1>Capítulo 1 - O Pequeno Computador Nasceu</H1>
    ...
    <H1>Capítulo 2 - A Primeira Tarefa do Pequeno Computador</H1>
    ...
    </BODY>
    </HTML>

Subcabeçalhos são marcados usando-se elementos H2 até H6.

Nota:Quanto usando modo ” book”, HTMLDOC inicia a criação com o primeiro elemento H1. Qualquer texto, imagem, tabela ou outros elementos visíveis, que precedam o primeiro H1 são silenciosamente ignorados. Por causa disso, certifique-se que o seu arquivo HTML contenha um elemento H1.


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.
add a comment

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.

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.
add a comment

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.

Princípios de reStructuredText 2011/02/01

Posted by gsavix in ciência colaborativa, 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, Doc, gerador documentos, Memorando, metodologia para receber ou transferir conhecimento, noticiário genérico, política, publicação jornal internet, publicador documentação, sociologia do conhecimento, Soft.
add a comment

reStructuredText Princípios

Esta seção é uma breve introdução aos conceitos e sintaxe de reStructuredText (reST), e pretende prover escritores com informação suficiente para criar documentos de maneira produtiva. Desde que reST foi desenhado para ser uma linguagem de marcação simples e não obstrutiva. .. seealso:

A documentação autorizada sobre Uso de Documentação está em
`reStructuredText <http://docutils.sourceforge.net/rst.html>`_.
Este endereço "ref" traz a descrição individual das construções em reST.

Parágrafos

O parágrafo (ref) é o bloco básico num documento reST. Parágrafos são simples conjuntos de textos, separados por uma ou mais linhas em branco. Como em Python, a indentação tem significado em reST, então todas as linhas do mesmo parágrafo precisam estar alinhadas à esquerda com o mesmo nível de indentação.

marcação Inline

Uma marcação padrão inline em reST é bem simples e usa:

  • um asterisco: *text* para ênfase (itálico),
  • dois asteriscos: **text** para ênfase (negrito),
  • backquotes: ``text`` para exemplos de código.

Se os asteriscos ou backquotes aparecerem em textos e forem confundidos com delimitadores de marcadores inline, eles deverão ser desviados com backslash (barra invertida).

Esteja alerta sobre algumas restrições das marcações:

  • não podem ser aninhadas,
  • o conteúdo não pode começar ou terminar por espaço em branco: * text* é errado,
  • precisam ser separadas e envolvidas por texto por caracteres especiais. Use backslash (barra invertida com espaço em branco) para lidar com: thisis\ *one*\ word.

Estas restrições podem deixar de existir nas futuras versões do docutils.

reST também permite configuração “role textos interpretados”, o que significa que texto delimitado, pode ser interpretado de maneira específica. Sphinx usa isso para providenciar marcação semântica e de referência cruzada dos identificadores, como descrito nas seções apropriadas. A sintaxe genérica :rolename:`content`.

reST padrão contém as seguintes roles:

Veja Inline markup para roles adicionadas pelo Sphinx.

Listas e Blocos

List markup (ref) is natural: just place an asterisk at the start of a paragraph and indent properly. The same goes for numbered lists; they can also be autonumbered using a # sign:

* This is a bulleted list.
* It has two items, the second
  item uses two lines.

1. This is a numbered list.
2. It has two items too.

#. This is a numbered list.
#. It has two items too.

Nested lists are possible, but be aware that they must be separated from the parent list items by blank lines:

* this is
* a list

  * with a nested list
  * and some subitems

* and here the parent list continues

Definition lists (ref) are created as follows:

term (up to a line of text)
   Definition of the term, which must be indented

   and can even consist of multiple paragraphs

next term
   Description.

Note that the term cannot have more than one line of text.

Quoted paragraphs (ref) are created by just indenting them more than the surrounding paragraphs.

Line blocks (ref) are a way of preserving line breaks:

| These lines are
| broken exactly like in
| the source file.

There are also several more special blocks available:

  • field lists (ref)
  • option lists (ref)
  • quoted literal blocks (ref)
  • doctest blocks (ref)

Código Fonte

Literal code blocks (ref) are introduced by ending a paragraph with the special marker ::. The literal block must be indented (and, like all paragraphs, separated from the surrounding ones by blank lines):

This is a normal text paragraph. The next paragraph is a code sample::

   It is not processed in any way, except
   that the indentation is removed.

   It can span multiple lines.

This is a normal text paragraph again.

The handling of the :: marker is smart:

  • If it occurs as a paragraph of its own, that paragraph is completely left out of the document.
  • If it is preceded by whitespace, the marker is removed.
  • If it is preceded by non-whitespace, the marker is replaced by a single colon.

That way, the second sentence in the above example’s first paragraph would be rendered as “The next paragraph is a code sample:”.

Tables

Two forms of tables are supported. For grid tables (ref), you have to “paint” the cell grid yourself. They look like this:

+------------------------+------------+----------+----------+
| Header row, column 1   | Header 2   | Header 3 | Header 4 |
| (header rows optional) |            |          |          |
+========================+============+==========+==========+
| body row 1, column 1   | column 2   | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2             | ...        | ...      |          |
+------------------------+------------+----------+----------+

Simple tables (ref) are easier to write, but limited: they must contain more than one row, and the first column cannot contain multiple lines. They look like this:

=====  =====  =======
A      B      A and B
=====  =====  =======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  =======

Sections

Section headers (ref) are created by underlining (and optionally overlining) the section title with a punctuation character, at least as long as the text:

=================
This is a heading
=================

Normally, there are no heading levels assigned to certain characters as the structure is determined from the succession of headings. However, for the Python documentation, this convention is used which you may follow:

  • # with overline, for parts
  • * with overline, for chapters
  • =, for sections
  • -, for subsections
  • ^, for subsubsections
  • ", for paragraphs

Of course, you are free to use your own marker characters (see the reST documentation), and use a deeper nesting level, but keep in mind that most target formats (HTML, LaTeX) have a limited supported nesting depth.

Explicit Markup

“Explicit markup” (ref) is used in reST for most constructs that need special handling, such as footnotes, specially-highlighted paragraphs, comments, and generic directives.

An explicit markup block begins with a line starting with .. followed by whitespace and is terminated by the next paragraph at the same level of indentation. (There needs to be a blank line between explicit markup and normal paragraphs. This may all sound a bit complicated, but it is intuitive enough when you write it.)

Directives

A directive (ref) is a generic block of explicit markup. Besides roles, it is one of the extension mechanisms of reST, and Sphinx makes heavy use of it.

Docutils supports the following directives:

  • Admonitions: attention, caution, danger, error, hint, important, note, tip, warning and the generic admonition. (Most themes style only “note” and “warning” specially.)
  • Images:
  • Additional body elements:
    • contents (a local, i.e. for the current file only, table of contents)
    • container (a container with a custom class, useful to generate an outer <div> in HTML)
    • rubric (a heading without relation to the document sectioning)
    • topic, sidebar (special highlighted body elements)
    • parsed-literal (literal block that supports inline markup)
    • epigraph (a block quote with optional attribution line)
    • highlights, pull-quote (block quotes with their own class attribute)
    • compound (a compound paragraph)
  • Special tables:
    • table (a table with title)
    • csv-table (a table generated from comma-separated values)
    • list-table (a table generated from a list of lists)
  • Special directives:
    • raw (include raw target-format markup)
    • include (include reStructuredText from another file) – in Sphinx, when given an absolute include file path, this directive takes it as relative to the source directory
    • class (assign a class attribute to the next element) [1]
  • HTML specifics:
    • meta (generation of HTML <meta> tags)
    • title (override document title)
  • Influencing markup:

    Since these are only per-file, better use Sphinx’ facilities for setting the default_role.

Do not use the directives sectnum, header and footer.

Directives added by Sphinx are described in Sphinx Markup Constructs.

Basically, a directive consists of a name, arguments, options and content. (Keep this terminology in mind, it is used in the next chapter describing custom directives.) Looking at this example,

.. function:: foo(x)
              foo(y, z)
   :module: some.module.name

   Return a line of text input from the user.

function is the directive name. It is given two arguments here, the remainder of the first line and the second line, as well as one option module (as you can see, options are given in the lines immediately following the arguments and indicated by the colons). Options must be indented to the same level as the directive content.

The directive content follows after a blank line and is indented relative to the directive start.

Images

reST supports an image directive (ref), used like so:

.. image:: gnu.png
   (options)

When used within Sphinx, the file name given (here gnu.png) must either be relative to the source file, or absolute which means that they are relative to the top source directory. For example, the file sketch/spam.rst could refer to the image images/spam.png as ../images/spam.png or /images/spam.png.

Sphinx will automatically copy image files over to a subdirectory of the output directory on building (e.g. the _static directory for HTML output.)

Interpretation of image size options (width and height) is as follows: if the size has no unit or the unit is pixels, the given size will only be respected for output channels that support pixels (i.e. not in LaTeX output). Other units (like pt for points) will be used for HTML and LaTeX output.

Sphinx extends the standard docutils behavior by allowing an asterisk for the extension:

.. image:: gnu.*

Sphinx then searches for all images matching the provided pattern and determines their type. Each builder then chooses the best image out of these candidates. For instance, if the file name gnu.* was given and two files gnu.pdf and gnu.png existed in the source tree, the LaTeX builder would choose the former, while the HTML builder would prefer the latter.

Alterado na versão 0.4: Added the support for file names ending in an asterisk.

Alterado na versão 0.6: Image paths can now be absolute.

Footnotes

For footnotes (ref), use [#name]_ to mark the footnote location, and add the footnote body at the bottom of the document after a “Footnotes” rubric heading, like so:

Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_

.. rubric:: Footnotes

.. [#f1] Text of the first footnote.
.. [#f2] Text of the second footnote.

You can also explicitly number the footnotes ([1]_) or use auto-numbered footnotes without names ([#]_).

Citations

Standard reST citations (ref) are supported, with the additional feature that they are “global”, i.e. all citations can be referenced from all files. Use them like so:

Lorem ipsum [Ref]_ dolor sit amet.

.. [Ref] Book or article reference, URL or whatever.

Citation usage is similar to footnote usage, but with a label that is not numeric or begins with #.

Substitutions

reST supports “substitutions” (ref), which are pieces of text and/or markup referred to in the text by |name|. They are defined like footnotes with explicit markup blocks, like this:

.. |name| replace:: replacement *text*

or this:

.. |caution| image:: warning.png
             :alt: Warning!

See the reST reference for substitutions for details.

If you want to use some substitutions for all documents, put them into rst_prolog or put them into a separate file and include it into all documents you want to use them in, using the include directive. (Be sure to give the include file a file name extension differing from that of other source files, to avoid Sphinx finding it as a standalone document.)

Sphinx defines some default substitutions, see Substitutions.

Comments

Every explicit markup block which isn’t a valid markup construct (like the footnotes above) is regarded as a comment (ref). For example:

.. This is a comment.

You can indent text after a comment start to form multiline comments:

..
   This whole indented block
   is a comment.

   Still in the comment.

Source encoding

Since the easiest way to include special characters like em dashes or copyright signs in reST is to directly write them as Unicode characters, one has to specify an encoding. Sphinx assumes source files to be encoded in UTF-8 by default; you can change this with the source_encoding config value.

Gotchas

There are some problems one commonly runs into while authoring reST documents:

  • Separation of inline markup: As said above, inline markup spans must be separated from the surrounding text by non-word characters, you have to use a backslash-escaped space to get around that. See the reference for the details.
  • No nested inline markup: Something like *see :func:`foo`* is not possible.

Footnotes

[1] When the default domain contains a class directive, this directive will be shadowed. Therefore, Sphinx re-exports it as rst-class.

Chamando sphinx-build 2011/02/01

Posted by gsavix in ciência colaborativa, civilização, 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, Doc, gerador documentos, língua portuguesa, Memorando, metodologia para receber ou transferir conhecimento, publicação jornal internet, publicador documentação, sociologia do conhecimento, Soft.
add a comment

Chamando sphinx-build

O script sphinx-build constrói um conjunto Sphinx de documentação. É chamado assim:

$ sphinx-build [opções] diretório-fonte diretório-documentos [arquivos]

onde diretório-fonte é diretório fonte, e and diretório-documentos é o diretório ou pasta onde será construída a documentação. Na maioria das vezes você não precisa especificar arquivos.

O script sphinx-build tem várias opções:

-b nome_do_construtor
É a opção mais importante: pois seleciona o tipo de construção. Os tipos mais comuns são:

html
Páginas HTML. É o construtor padrão.
dirhtml
Páginas HTML, mas um diretório para cada documento. Gera simples URLs (sem .html usado em muitos webserver).
singlehtml
Um único arquivo HTML, com todo o conteúdo.
htmlhelp, qthelp, devhelp, epub
Arquivos HTML, com informações específicas e adicionais para construir coleção de documentação para estes formatos.
latex
Constrói fontes LaTeX, que se compilados podem gerar documento PDF. utiliza para isso o programa pdflatex.
man
Contrói páginas no formato groff (man em sistemas UNIX).
text
Constrói arquivos texto.
doctest
Executa todos os doctests na documentação, se a extensão doctest foi habilitada.
linkcheck
Verifica a integridade de todos links externos.

Veja construtores para uma lista de todos construtores enviados com o Sphinx. Extensões podem adicionar seus próprios construtores.

-a
Se informada, sempre irá gravar todos os tipos de arquivos. O padrão é só gerar saída para arquivos novos ou fontes modificados. (Isto pode não se aplicar a todos os construtores).

-E
Don’t use a saved environment (the structure caching all cross-references), but rebuild it completely. The default is to only read and parse source files that are new or have changed since the last run.

-t alvo
Define o alvo alvo. Isto é relevante para diretivas only que só incluem seu conteúdo se o alvo foi habilitado.

Novo na versão 0.6.

-d caminho
Since Sphinx has to read and parse all source files before it can write an output file, the parsed source files are cached as “doctree pickles”. Normally, these files are put in a directory called .doctrees under the build directory; with this option you can select a different cache directory (the doctrees can be shared between all builders).

-c path
Don’t look for the conf.py in the source directory, but use the given configuration directory instead. Note that various other files and paths given by configuration values are expected to be relative to the configuration directory, so they will have to be present at this location too.

Novo na versão 0.3.

-C
Don’t look for a configuration file; only take options via the -D option.

Novo na versão 0.5.

-D setting=value
Override a configuration value set in the conf.py file. The value must be a string or dictionary value. For the latter, supply the setting name and key like this: -D latex_elements.docclass=scrartcl. For boolean values, use 0 or 1 as the value.

Alterado na versão 0.6: The value can now be a dictionary value.

-A name=value
Make the name assigned to value in the HTML templates.

Novo na versão 0.5.

-n
Run in nit-picky mode. Currently, this generates warnings for all missing references.

-N
Do not emit colored output. (On Windows, colored output is disabled in any case.)

-q
Do not output anything on standard output, only write warnings and errors to standard error.

-Q
Do not output anything on standard output, also suppress warnings. Only errors are written to standard error.

-w arquivo
Grave avisos (warnings e errors) para cada arquivo, em adição ao padrão de erros.

-W
Trate avisos (warnings) como erros. Isto significa que o construtor irá parar ao primeiro erro e o sphinx-build termina com status de saída 1.

-P
(Useful for debugging only.) Run the Python debugger, pdb, if an unhandled exception occurs while building.

You can also give one or more filenames on the command line after the source and build directories. Sphinx will then try to build only these output files (and their dependencies).

Opções do Makefile

Os arquivos Makefile e make.bat são criados pelo programa sphinx-quickstart normalmente executado sphinx-build só com as opções -b e -d. Contudo, são suportadas as seguintes variáveis com suas descrições:

PAPER
O valor para latex_paper_size.

SPHINXBUILD
O comando para usar ao invés de sphinx-build.

BUILDDIR
O diretório onde será construído, ao invés do escolhido pelo sphinx-quickstart.

SPHINXOPTS
Opções adicionais para o programa sphinx-build.

 

© Copyright 2011, Biblioteca Nuto Santana e outros. Criado com Sphinx 1.0.7

Primeiros passos com o Sphinx 2011/02/01

Posted by gsavix in ciência colaborativa, colaboração na aquisição conhecimento, como gerar documentos a partir dos programas fonte, como publicar na internet gratuitamente, Computadores, Conhecimento para receber ou transferir tecnologia, Doc, Memorando, metodologia para receber ou transferir conhecimento, publicação jornal internet, publicador documentação, sociologia do conhecimento, Soft.
Tags: , , , , , ,
add a comment

Primeiros passos com Sphinx

Esse documento é para permitir uma visão como um tutorial, nas tarefas mais comuns no uso do Sphinx.

A seta verde designa “mais informações”, através de ligações para seções avançadas descrevendo a tarefa.

Configurando fontes da documentação

O diretório ou pasta raiz, da coleção tem o nome de source directory. Nele também está o arquivo de configuração Sphinx conf.py, onde você pode configurar todos os aspectos, sobre como o Sphinx faz a leitura dos seus fontes e constrói sua documentação. [1]

O Sphinx vem com um script chamado sphinx-quickstart que configura on diretório ou pasta fonte, além de criar um arquivo padrão chamado conf.py com as opções mais comuns, a partir de poucas perguntas feitas para você. Apenas execute:

$ sphinx-quickstart

e responda as perguntas. (Certifique-se de responder yes para a extensão “autodoc”.)

Definindo a estrutura do Documento

Vamos assumir que você já executou sphinx-quickstart. Foi criado um diretório ou pasta contendo o arquivo conf.py e um arquivo com documento mestre index.rst (se você aceitou os padrões). A função principal do master document é servir como página de boas vindas, e conter a raiz da TOC (tabela de Conteúdos) ou (toctree). Isto é uma das principais coisas que o Sphinx adiciona ao reStructuredText, (RST) uma maneira de conectar múltiplos arquivos em uma hierarquia única hierarquia de documentos.

Diretivas reStructuredText

toctree é uma directiva de reStructuredText, uma peça versátil de markup. Diretivas podem conter argumentos, opções e conteúdo.

Argumentos são fornecidos diretamento após (dois pontos) seguidos pelo name da diretiva. Cada diretiva decide quando e quantos argumentos pode ter.

Opções são fornecidas após os argumentos, na forma de “lista de campos”. O maxdepth é uma opção para a diretiva toctree.

Conteúdo seguindo Argumentos ou Opções após uma linha em branco. Cada diretiva decide quando pode haver conteúdo e o que fazer com ele.

Uma pegadinha com diretivas é que a primeira linha do conteúdo precisa estar “indentada” (ou alinhada) à mesma coluna onde a opção está.

A diretiva toctree inicialmente está vazia, e parece com:

.. toctree::
   :maxdepth: 2

Você adiciona documentos na lista, preenchendo o Conteúdo da diretiva:

.. toctree::
   :maxdepth: 2

   intro
   tutorial
   ...

É exatamente assim que toctree para documentação parece. Os documentos para incluir são colocados como nome do documento, os quais de maneira resumida, significa que você não quis informar as extensão do arquivo, e vai utilizar a barra como separador de diretórios ou pastas.

more Leia mais sobre Diretiva toctree.

Você pode criar os arquivos que você inseriu em toctree e adicionar conteúdo, e os títulos deles serão inseridos até o nível especificado por “maxdepth” da diretiva toctree. Agora, o Sphinx sabe a ordem e a hierarquia dos documentos, os quais podem conter diretivas toctree neles mesmos, o que significa que você pode especificar várias hierarquias subordinadas se necessário.

Adicionando conteúdo

Em arquivos fonte Sphinx, você pode usar muitas funcionalidades padrão de (RST) reStructuredText. Além destas, existem outros adicionadas pelo Sphinx. Por exemplo, você pode adicionar referências cruzadas entre arquivos, de uma maneira portável (pois funcionam para todos os tipos de saída), através de ref role.

Por exemplo, se você está vendo a versão HTML, você pode dar uma olhada na fonte do documento – usando o link “Exibir Código Fonte” na barra lateral.

more Veja reStructuredText Princípios para maiores detalhes ao reStructuredText e marcas_sphinx para uma lista completa de marcações adicionadas pelo Sphinx.

Rodando o build

Agora que você adicionou alguns arquivos e conteúdos, vamos fazer nosso primeiro “build” (construir) dos documentos. A construção é iniciada com o programa sphinx-build, o qual é chamado como:

$ sphinx-build -b html diretório_fonte diretório_construído

onde diretório-fonte é onde estão seus arquivos reStructuredText e o diretório_construído é o diretório ou pasta onde você deseja colocar a documentação construída. A opção -b seleciona o construtor; nesse exemplo Sphinx irá construir arquivos HTML.

mais informações Veja chamada para todas as opções que o programa sphinx-build permite.

Contudo, o script sphinx-quickstart cria um arquivo a Makefile e um arquivo make.bat que tornam a vida mais fácil para você, pois para criar a documentação você só precisa escrever:

$ make html

para construir docs HTML no diretório que você escolheu. Execute make sem argumento para ver quais possibilidades estão disponíveis.

Documentando objetos

Um dos principais objetivos do Sphinxs, é a documentação fácil de objetos objetos (em termos gerais) em qualquer domínio. Um domínio é uma coleção de tipos de objetos, que juntos com marcas, criam e referenciam descrições a estes objetos.

O domínio mais importante é o Python. Por ex.: a função interna enumerate(), você pode adicionar isto aos seus arquivos fonte:

.. py:function:: enumerate(sequence[, start=0])

   Retorna um iterator que aponta tuples de um índice e um item de
   *sequência*. (E assim sucessivamente.)

Isso é renderizado (deduzido) como:

enumerate(sequence[, start=0])
Retorna um iterator que aponta tuples de um índice e um item de
sequência. (E assim sucessivamente.)

O argumento da diretiva é a assinatura do objeto que você descreve, o conteúdo é a documentação dele. Múltiplas assinaturas podem ser dadas, cada uma em sua linha.

O domínio Python também ocorre como domínio padrão, portanto você não precisa colocar o prefixo de marcação no nome do domínio:

.. function:: enumerate(sequence[, start=0])

   ...

faz o mesmo se você manter a configuração padrão para domínio.

Existem muitos outras diretivas para documentar outros tipos de objetos Python, por exemplo: py:class or py:method. Existe também uma definição de referência cruzada role para cada um desses objetos. Essa marcação irá criar uma ligação em enumerate():

A função :py:func:`enumerate` pode ser usada para ...

E aqui a prova: Um link para enumerate().

Recapitulando, o prefixo py: pode ser omitido para o domínio Python pois é o padrão. Não importa qual arquivo contem a documentação para enumerate(); O Sphinx irá encontrar e criar um link para este arquivo.

Cada domínio terá regras especiais para como são as assinaturas e fazer a saída formatada aparecer bem formatada ou adicionar funcionalidades como ligação para tipos de parâmetros, ex. em domínios C/C++.

more Veja domínios para todas as diretivas e roles disponíveis.

Configurações básicas

Anteriormente mencionamos que o arquivo conf.py controla como o Sphinx processa seus documentos. Quando este arquivo, é executado como um fonte Python, você assinala cada um dos valores, nele existentes. Para usuários avançados: deste que executado pelo Sphinx, você pode executar tarefas não triviais, a partir deste arquivo, como extensão sys.path our importar um módulo para encontrar a versão que você está documentando. Os valores configurados que você provavelmente deseja modificar, já foram gravados no arquivo conf.py pelo sphinx-quickstart e inicialmente definidos como comentários com a sintaxe padrão Python # torna comentário o resto da linha. Para modificar o valor padrão, remova o # e modifique o conteúdo da variável para o valor desejado. Para personalizar um valor que não foi automaticamente adicionado pelo programa sphinx-quickstart, apenas faça um assinalamente adicional.

Tenha em mente que o arquivo utiliza sintaxe do Python para strings, números, listas e assim por diante. O arquivo é salvo em unicode UTF-8 por padrão como indicado pela declaração de codificação da primeira linha. Se você usar caracteres não ASCII em qualquer valor de string, você precisa utilizar Python Unicode (como project = u'Exposé').

mais informações Veja Arquivo de configuração do build para documentação de todos os valores disponíveis.

Autodoc

Quando documentar código Python, é comum colocar um monte de documentação nos arquivos fonte, em strings de documentação. Sphinx suporta a inclusão de docstrings a partir de seus módulos com uma extensão (uma extensão é um módulo Python que provê funcionalidades adicionais para os projetos Sphinx) chamada “autodoc”.

Para utilizar autodoc, você precisa ativar esta extensão no arquivo conf.py colocando a string 'sphinx.ext.autodoc' na lista assinalada contendo extensions. Então você terá mais diretivas à sua disposição.

Por exemplo, para documentar a função io.open(), lendo sua assinatura e a docstring do arquivo fonte, você escreverá:

.. autofunction:: io.open

Você também pode documentar todas as classes ou mesmo todos os módulos, automáticamente usando as opções de membros para diretivas auto, ficando assim:

.. automodule:: io
   :members:

autodoc precisa importar seus módulos para extrair as docstrings. Todavia, você precisar adicionar o caminho correto para sys.path no seu arquivo conf.py.

mais informações Veja sphinx.ext.autodoc para descrição completa para funcionalidades autodoc.

Mais tópicos serão cobertos

  • Outras extensões (math, intersphinx, viewcode, doctest)
  • Arquivos Státicos
  • Selecionando um tema
  • Modelos (Templating)
  • Usando extensions
  • Escrevendo extensões

Notas de Rodapé

[1] Essa é a formatação usual. Contudo, o arquivo conf.py pode também estar em outro diretório ou pasta, o diretório de configuração. Veja Chamando sphinx-build.

Conte sua notícia como um profissional 2010/04/10

Posted by gsavix in Conhecimento, Doc, língua portuguesa, Memorando, noticiário genérico, www.auvix.com.br.
Tags: , , , , ,
add a comment

www.auvix.com.br auvix informática
São Paulo, 10 de abril de 2010 iReport Toolkit

Conte sua notícia como um profissional

Os ingredientes de uma boa notícia

Nós perguntamos para alguns repórteres, produtores e editores da CNN, o que eles encontram numa boa reportagem e como eles constroem uma. Surgiram então algumas palavras de conselho:

Em primeiro as coisas iniciais: sua notícia precisa incluir as informações básicas 5w e 1h (who, what, where, when, why e how) (quem, o que, onde, quando, por que e como). Precisa ser verdadeira e precisa ser interessante.

Conexões. Alguém precisa cuidar das pessoas da notícia ou a notícia não vale a pena ser contada. É seu trabalho como contador de notícias explicar porque alguém deve envolver-se.

Ela deve ser contada em palavras que todos nós usamos e entendemos. Se você ligar para seu melhor amigo e contar-lhe a notícia, por onde você começaria? E como você descreveria a notícia? Esta é a melhor parte e a maneira mais simples de contá-la. Comece por aí e veja aonde isto te leva.

Ela precisa ter continuidade. Se você deseja que sua audiência conheça o que acontece em seguida, construa o desenrolar com narrativa, informações, sons naturais e se estiver trabalhando com video, uma edição criativa.

Ela precisa parecer real. Emoção é um potente conector e pode levar a um longo caminho a frente, ajudando a nos entendermos uns aos outros. Pense em como você pode usar imagens, sons e palavras para expressar a emoção da notícia e suas particularidades.

Faça um esboço ou mapeamento. Se você planeja editar um video, coloque junto uma galeria de fotos ou escreva um texto para a notícia, geralmente isso ajuda a no planejamento da ação.

Qual são os detalhes cruciais?
Qual é a parte mais importante?
Como as partes se conectam?
Rascunhe ou faça um “sketch storyboard” antes de começar com o árduo trabalho de escrever e editar.

Você será recompensado pelo que você fizer !!!

extraído e traduzido de http://www.ireport.com/toolkit.jspa

Em busca do povo brasileiro 2009/08/07

Posted by gsavix in civilização, Doc, Memorando, política, povo.
Tags: , , , , , ,
add a comment

Ridenti, Marcelo

Em busca do povo brasileiro, Rio de Janeiro, Editora Record, 2000

Onde está, ou esteve, ou estará o povo brasileiro? será possível encontrá-lo em algum lugar? no coração do brasil ele estará, nas matas cerradas, entre os índios? ou nos braços rudes dos lavradores, esquecidos de todas as lembranças, crestados de tanto sol e labuta? no canto dos pescadores, puxando o arrastão, ou entre os trabalhadores manuais, imaginados como coveiros da ordem? estará o povo no sertão das vidas secas que um dia ainda vai virar mar? ou nas sampas delirantes e trepidantes, com seus viadutos e zumbidos atordoantes?

isbn 85-01-05851-3 cdd 701.03 cdu 7:32

copyright 2000 by marcelo ridenti

pedidos pelo reembolso postal caixa postal 23.052 Rio de Janeiro, RJ – 20922-970

A morte de Virgílio [Der Tod des Vergil] 2009/01/26

Posted by gsavix in Doc.
Tags: ,
add a comment

UTC-2

Ainda jovem, Broch assumiu a direção de uma empresa industrial de seu pai, herdeiro de família rica e tradicional austríaca. Somente depois dos quarenta anos resolveu escrever, começando com uma trilogia romanesca intitulada Os Sonâmbulos, um mosaico sobre a Alemanha da passagem do século.

Na Segunda Guerra Mundial quando a Alemanha invadiu a Áustria, em 1938, Broch emigrou para os Estados Unidos e ali dedicou-se a estudos de psicologia e comportamento, recebendo um prêmio da Fundação Rockfeller(* sic). Fez pesquisas na universidade de princeton, e nesse meio-tempo publicou dois romances: A grandeza desconhecida (1933) e a morte de virgílio (1947). Escreveu em seguida um ensaio consagrador sobre a obra de James Joyce, de quem admite ter recebido grande influência.
O romance-poema A Morte de Virgílio tem sido situado entre as obras maiores de literatura de ficção no século XX.

A renovação do gênero romance deve-se a Broch, tanto quanto a Kafka, Joyce e Musil. Seu método de comentário lírico, tornou-se célebre e é através dele que os últimos dias do poeta Virgílio são imaginados pelo autor. Na época em que escreveu a obra, o escritor estava dedicado há muito ao estudo da filosofia, da matemática e da psicologia. Até sua morte em New Haven, no final de 1951, Broch publicou pequenos ensaios e realizou conferências. “A visão do mundo proporcionada pelo romance” foi um dos seus trabalhos que mais repercussão tiveram na época.O tema de A Morte de Virgílio mistura a lenda e a verdade histórica, e ele foi concebido pelo autor numa prisão da Gestapo, onde passou cinco semanas antes de fugir para os Estados Unidos.

Foi em Princeton que a idéia foi desenvolvida, tendo aparecido em inglês e alemão no ano do término da Segunda Guerra. O monólogo interior de Virgílio é um debate de Hermann Broch consigo mesmo, em torno da crise espiritual do século e às voltas com a transcendência recusada no dia-a-dia. Dúvidas sobre a procedência do trabalho poético, sobre a ignorância que cerca o homem, sobre a função da arte num período de violência e angústia, foram transferidas para esse romance magistral, que fala ao leitor em função do grau de sua sensibilidade.

transcrição efetuada por

Gilberto dos Santos Alves