Guias de estilo para linguagem de marcação

Esta página aborda as convenções para escrita e utilização da sintaxe da linguagem de marcação reStructuredText (RST).

Convenções

  • Indentação de três espaços.
  • As linhas devem ter menos de 120 caracteres de comprimento total.
  • Utilize itálico para os nomes de botões e menus.

Outras convenções menos restritivas:

  • Evite o uso de caracteres unicode.
  • Evite utilizar textos com envoltura excessiva (ou seja, as sentenças devem possuir suas próprias linhas).

Encabeçamentos

#################
  Document Part
#################

****************
Document Chapter
****************

Document Section
================

Document Subsection
-------------------

Document Subsubsection
^^^^^^^^^^^^^^^^^^^^^^

Document Paragraph
""""""""""""""""""

Nota

Os encabeçamentos marcados como Part na imagem de exemplo, somente devem ser usados em conteúdos principais ou nos índices das páginas.

Nota

Cada um dos arquivos .rst somente devem ter somente um encabeçamento referenciando o capítulo, usando (*) por arquivo.

Estilização de textos

Veja a visão geral sobre ReStructured Text (em inglês) para mais informações sobre como estilizar os vários elementos da documentação e como adicionar listas, tabelas, figuras e blocos de código. A referência do sistema Sphinx (em inglês) fornece mais algumas ideias adicionais para construções dos textos.

Os seguintes exemplos são marcações úteis para a estilização dos textos:

*italic*
**bold**
``literal``

Elementos de interface

  • :kbd:`BEM` – Atalhos para teclado e mouse.
  • *Espelhar* – Rótulos de interface.
  • :menuselection:`Janela de visualização 3D --> Adicionar --> Malha --> Macaco` – menus.

Exemplos de código

Existe suporte para realce de sintaxe caso a linguagem de programação seja fornecida, e os números de linha podem ser opcionalmente mostrados usando a opção :linenos:

.. code-block:: python
   :linenos:

   import bpy
   def some_function():
       ...

Imagens

A marcação «Figures» deve ser usada para informar a inserção de imagens:

.. figure:: /images/render_cycles_nodes_types_shaders_node.png

   Image caption.

Por consistência, e devido ao fato de ser bom garantir que as imagens de tela tenham todas um tamanho similar quando deslocadas ou realocadas próximas aos textos, os escritores devem obter as imagens de tela da seguinte maneira:

  1. Prepare the area you would like to capture making sure to use the default theme and setting. (In some cases you may not want to use the default settings e.g. if some options are hidden behind a checkbox.)
  2. Amplie para o tamanho máximo de ampliação (Mantendo pressionada a tecla Tecl. Num. + ou usando Ctrl-BMM ou comandos similares).
  3. Reduza a ampliação em oito níveis (pressionando Tecl. Num. - (menos) – oito vezes).
  4. Em alguns casos, você vai querer deixar uma pequena margem em torno das coisas que você está tentando capturar para demonstrar. Esta área, deve ser em torno de cerca de 30px mas não precisa ter essa medida exata.

Isto pode ser aplicado a diversas partes da interface mas pode não funcionar em todos os casos.

Arquivos

Sem capitulações e sem espaços
Os nomes de arquivo devem ser escritos em minúsculo, com sublinhados entre as palavras.
Ordene itens de maneira útil
Posicione o ordenamento das nomenclaturas com identificadores específicos no final dos textos.
Formato

Use .png para as imagens que possuem cores sólidas como imagens de tela da interface do Blender, e .jpg para as imagens com grande quantidade de variação de cor, como fotografias e exemplos de renderização.

Não utilize arquivos do tipo .gif animados, eles são difíceis de ser mantidos, podem causar distrações e comumente, são arquivos grandes em seu tamanho. Caso um vídeo demonstrativo seja necessário, utilize uma referência ao YouTube ou Vimeo (Veja a seção Vídeos logo abaixo).

Localização
Coloque as imagens dentro da pasta manual/images no repositório do manual. Não utilize outras sub-pastas.
Nomenclatura

Para a nomenclatura dos arquivos, use sublinhados para separar os capítulos e seções, e use traços para separar as seções que possuem duas ou mais palavras. Portanto, os nomes dos arquivos de imagens devem se parecer com o seguinte exemplo: chapter_subsection_sub-subsection_id.png.

  • interface_splash_current.png
  • interface_undo-redo_last.png
  • interface_undo-redo_repeat-history-menu.png

Não utilize caracteres especiais ou espaços!

Guias de utilização

  • Evite especificar a resolução da imagem, de maneira que o tema possa gerenciar as imagens de maneira consistente e forneça o melhor esquema de apresentação entre diferentes tamanhos de tela.

  • Ao documentar um painel ou uma seção da interface de usuário, é melhor utilizar uma única imagem que mostre todas as áreas relevantes (ao invés de múltiplas imagens para cada ícone ou botão), posicionadas no topo da seção que você está escrevendo, e então explicar as funcionalidades na ordem em que elas aparecem na imagem.

    Nota

    É importante que o manual possa ser mantido por um longo período de tempo, e que as mudanças na interface de usuário e nas opções evite a necessidade de muitas imagens (quando elas não são especialmente necessárias). Caso contrário, isto se tornará um problema gigantesco para a manutenção da documentação.

Vídeos

Os vídeos referenciados no Youtube™ e Vimeo™ podem ser embutidos na página usando:

.. youtube:: ID

.. vimeo:: ID

O ID (Identificador) é encontrado na URL completa do vídeo, por exemplo:

  • O ID para https://www.youtube.com/watch?v=Ge2Kwy5EGE0 é Ge2Kwy5EGE0
  • O ID para https://vimeo.com/15837189 é 15837189

Guias de utilização

  • Evite a adição de vídeos que dependem de explicações em formato de voz, pois estes são difíceis de ser traduzidos.
  • Não insira vídeos de tutoriais embutidos como formas de explicar uma funcionalidade, a escrita em si deverá explicá-la adequadamente (mesmo que você possa incluir uma ligação para o vídeo no final da página sob o encabeçamento para tutoriais ( Tutoriais, na imagem de referência).

Construções úteis

  • |BLENDER_VERSION| – Resolve o número da versão atual do Blender.
  • :abbr:`SSAO (Oclusão ambiente em espaço de tela)` – As abreviações mostram um texto completo como uma dica de ferramenta para o leitor.
  • :term:`Contíguo` – Vincula o texto para uma entrada presente no Glossário.

Referências cruzadas e ligações

Você pode criar ligações para outros documentos dentro do manual usando:

:doc:`The Title </section/path/to/file>`

Para fazer uma ligação a uma seção específica em outro documento (ou dentro do mesmo), as seguintes rotulações explícitas estão disponíveis:

.. _sample-label:

[section or image to reference]

Some text :ref:`Optional Title <sample-label>`

Ligações para um título dentro do mesmo arquivo:

Titles are Targets
==================

Body text.

Implicit references, like `Titles are Targets`_

Ligações para o mundo externo:

`Blender Website <https://www.blender.org>`__

Esquema de diretórios

As seções em geral devem ser estruturadas da seguinte maneira:

  • directory_name/
    • index.rst (contém ligações para arquivos internos)
    • introduction.rst
    • section_1.rst
    • section_2.rst

Por exemplo:

  • rendering/
    • index.rst
    • cycles/
      • index.rst
      • introduction.rst
      • materials/
        • index.rst
        • introduction.rst
        • volumes.rst

A ideia é encapsular todos os conteúdos de uma seção dentro de uma pasta. O ideal é que cada seção deva ter um arquivo index.rst (contendo a tabela de conteúdos (TOC) para esta seção) e um arquivo de nome introduction.rst (apresentação) para os conteúdos de cada seção.

Tabela de conteúdos

Por padrão uma tabela de conteúdos deve mostrar dois níveis de profundidade:

.. toctree::
   :maxdepth: 2

   introduction.rst
   perspective.rst
   depth_of_field.rst

Leituras adicionais

Para aprender mais sobre o sistema reStructuredText, veja:

Estreando no sistema Sphinx RST (em inglês)
Uma boa introdução básica.
Referência para utilitários de documentos reStructuredText (em inglês)
Ligações para referência e documentações do usuário.