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

See the overview on ReStructuredText for more information on how to style the various elements of the documentation and on how to add lists, tables, pictures and code blocks. The Sphinx reference provides more insight additional constructs.

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

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

Interface Elements

  • :kbd:`BEM` – Atalhos para teclado e mouse.

  • *Espelhar* – Rótulos de interface.

  • :menuselection:`3D Viewport --> Add --> Mesh --> Monkey` – 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/interface_window-system_splash_current.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 a área que você deseja capturar certificando-se que está utilizando o tema e definições padrão do software. (Em alguns casos, talvez você não queira usar as configurações padrão, por exemplo, caso algumas opções estiverem escondidas atrás de uma caixa de marcação).

  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.

Format

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 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

Videos from YouTube™ can be embedded using:

.. youtube:: ID

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

The ID for https://www.youtube.com/watch?v=Ge2Kwy5EGE0 is Ge2Kwy5EGE0.

Guias de utilização

  • Avoid adding videos that rely on voice, as this is difficult to translate.

  • Do not embed video tutorials as a means of explaining a feature, the writing itself should explain it adequately (though you may include a link to the video at the bottom of the page under the heading Tutorials).

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>`__

Context Sensitive Manual Access

It is possible to link to a specific part of the manual from in Blender by opening the context menu (right click) of a property or operator and selecting Online Manual. In order for this to work, this needs to be accounted for in the documentation. To link a property or operator to a specific part of the manual you need to add an external reference link tag whose ID matches Blender’s RNA tag. The easiest way to find out what the tag for a property is to open the context menu of the property/operator and select Online Python Reference to extract the tag from the URL. Some examples of how this looks in the RST document are given below:

.. _bpy.types.FluidDomainSettings.use_fractions:

Fractional Obstacles
   Enables finer resolution in fluid / obstacle regions (second order obstacles)...

   .. _bpy.types.FluidDomainSettings.fractions_distance:

   Obstacle Distance
      Determines how far apart fluid and obstacles are...

For an operator:

.. _bpy.ops.curve.subdivide:

Subdivide
=========

Further Reading

Para aprender mais sobre o sistema reStructuredText, veja:

Sphinx RST Primer

Uma boa introdução básica.

Docutils reStructuredText Reference

Ligações para referência e documentações do usuário.