Views
Tutorial ReST
Document Actions
O que é ReST
ReST significa texto reestruturado, ou reStrucured Text (RST), e é uma derivação de uma outra notação chamada texto estruturado, ou Structured Text(STX), com uma série de melhorias.
ReST é um mecanismo de composição e formatação de documentos, baseado em marcações visualmente simples e altamente legíveis em arquivos texto. Essa notação foi criada no projeto Docutils como ferramenta para escrever documentação na linguagem python. Hoje em dia, várias instituições e projetos estão adotanto o reST como formato padrão para escrever documentos, pelo poder e flexibilidade e extensibilidade da notação.
Mais um Formato? Por que não usar HTML?
A grande vantagem do reST é que uma vez terminado, o texto pode ser convertido para vários outros formatos, como HTML, XML, LaTeX etc. Se o texto fosse escrito em HTML, o formato estaria fixo, e converter HTML em outro formato é sempre um processo mais trabalhoso.
Os conversores existentes podem ser encontrados no site do projeto Docutils
O reST enfatiza a separação entre estrutura e apresentação visual de um texto. Deste modo, utilizando uma folha de estilos (CSS) diferente, um texto pode ser exibido de formas radicalmente diferentes.
O objetivo do reST é estabelecer um padrão para expressar a estrutura de um texto sem precisar de um editor especial, criando mecanismos diversos que traduzam esse texto para vários formatos.
Como começar
Na Incubadora, existem duas formas de se utilizar o texto reestruturado:
- QuickDoc: é um tipo de documento desenvolvido especialmente para ser utilizado com o reST. Diferente do Documento, ele não utiliza o editor visual, contando somente com uma caixa de texto para a edição do conteúdo. Em qualquer QuickDoc é possível acessar o código fonte em reST que foi utilizado para gerá-lo, usando o link no canto superior direito chamado exibir fonte.
- Wiki: qualquer página wiki pode ser composta utilizando a notação reST. Inclusive, esta é a notação padrão recomendada na Incubadora. Qualquer membro da Incubadora pode ver o código fonte usado para gerar aquela página wiki clicando na aba edição da página. Este tutorial está num wiki escrito em reST, portanto você também pode acessar o código fonte e ver como ele foi construído.
Dicas básicas de formatação
Títulos e subtítulos
Títulos e subtítulos de seções são criados através de um "adorno": uma linha de caracteres de pontuação ASCII abaixo (ou acima E abaixo) do título. A linha tem que ter no mínimo a mesma quantidade de caracteres que o título (pode ter mais). Exemplo:
-------------- Nivel 1 -------------- bla, bla, bla Nivel 2 =========== bli, bli, bli
Na verdade, não existe um padrão rígido que associa determinado tipo de adorno a um nível hierárquico específico. O ReST entende o primeiro adorno usado no texto como nível 1, a segunda como nível 2, e assim por diante.
Exemplos literais
Para colocar um exemplo de código após um parágrafo, basta terminá-lo com um par de dois pontos (::) e identar o texto que irá no box. Veja o exemplo acima, onde está demonstrada a sintaxe dos títulos de seções.
Trechos de código em python podem ser inseridos utilizando o prompt de comando do python, mesmo sem identar o texto ou usar o duplo dois pontos.
>>> test()
Estilos de texto
Para usar o itálico basta colocar um asterisco (*) antes e depois da palavra:
*italico*, *duas palavras*
Para o negrito é preciso dois asteriscos antes e depois da palavra:
**negrito**, **duas palavras**
Como exercício, experimente subir e descer 10 andares carregando 6 melancias.
Para marcar o texto com uma fonte especial que denota símbolos de uma linguagem de programação, como while, usa-se dois pares de crase.
Links
Para fazer um link anônimo basta colocar um sinal de __ no final de uma palavra. Se o link estiver em mais de uma palavra, é preciso cercar o texto com uma crase antes e uma depois.
Para especificar o alvo de um link anônimo, existem três maneiras:
-na mesma linha: basta colocar a URL dentro das crases envolta pelos sinais < e >, por exemplo:
`exemplo de link para o Google <http://www.google.com>`__
-em outra linha: para deixar o texto mais limpo, é recomendável colocar os links em outra linha, ou no final do texto. Para isso basta começar uma linha com __ e colocar o endereço logo depois. Por exemplo:
`exemplo de link para a Incubadora`__ __ http://iv.fapesp.br/
Também é possível usar links com nomes, o que facilita ainda mais a organização do documento. Para isso basta colocar um único _ ao final de uma palavra ou ao final de um bloco cercado de crases. O nome do link é o texto da(s) palavra(s) marcada(s). Para especificar o alvo a sintaxe é:
.. _nome do alvo: <URL> (colocado no início de uma linha)
Mais exemplos:
link anônimo__ __ /portal/doc `outro link anônimo, com várias palavras e vírgula`__ __ COMOCriarEEditarTextosEmReSTReStructuredText clique aqui_ para ir para a Incubadora. .. _aqui: http://iv.fapesp.br/ `este link tem um nome`_ .. _este link tem um nome: /portal/doc#top
Créditos: agradecemos a contribuição de Luciano Ramalho, do projeto pensarpython
Veja também COMO criar e editar textos em reST (reStructured Text)
Forgot your password?
Incubadora marca presença em congresso argentino de Software Livre
