Guia de estilo da documentação¶

Este guia inclui informações sobre o estilo esperado, a sintaxe específica do MkDocs, as várias ferramentas necessárias e a tradução da documentação, com relação à redação de novos conteúdos e à tradução de conteúdos existentes.

Estilo geral¶

Os cabeçalhos e títulos devem ter apenas a primeira palavra em letra maiúscula.
Preferimos a ortografia dos EUA, com algumas liberdades para o coloquialismo específico da programação (por exemplo, "apps") e a verbalização de substantivos (por exemplo, "scrollable").
A grafia de "artefact" e "artefacts" é a mostrada.
Usamos espaços simples após um ponto final.
Usamos um único hífen rodeado por espaços como travessão (ou um literal HTML —).
Qualquer referência a um nome de produto deve usar a capitalização preferencial do produto. (por exemplo, "macOS", "GTK", "pytest", "Pygame", "PyScript").
Se um termo estiver sendo usado "como código", ele deverá ser citado como código embutido, envolvendo-o em pontos finais simples, em vez de ser adicionado ao dicionário.
Evitamos usar termos como “simplesmente”, “apenas” ou “facilmente” ao descrever ações que o usuário deve realizar. Esses termos podem ser interpretados como pejorativos, especialmente quando o usuário está enfrentando dificuldades.

Informações de referência cruzada¶

Você deve fazer referência cruzada ao conteúdo da documentação sempre que possível. Esta seção aborda as várias maneiras de fazer isso, cada uma delas baseada no tipo de informação que está sendo referenciada.

O MkDocs renderiza links padrão formatados em Markdown. Os hiperlinks da Web com formatação Markdown padrão são os seguintes:

[Link text](https://example.com/)

Você também pode usar esse formato para vincular a um arquivo local:

[Link text](path/to/file.md)

Para fazer referência a seções específicas de arquivos ou à documentação da API, é necessário usar o formato de link de referência do MkDocs.

Âncoras Markdown personalizadas e referência cruzada de conteúdo¶

O Markdown gera âncoras para todos os cabeçalhos (qualquer coisa em uma única linha que comece com um a seis símbolos #), com base no conteúdo do cabeçalho. Por exemplo, a âncora gerada para esta seção é custom-markdown-anchors-and-content-cross---referencing. No entanto, devido à maneira como nossas traduções funcionam, sempre que um cabeçalho de seção for referenciado, ele deverá ter uma âncora personalizada.

O MkDocs suporta a renderização de uma sintaxe de link de referência que permite que você crie links para vários outros elementos na documentação usando um link Markdown modificado. Isso inclui links para, entre outras coisas, cabeçalhos Markdown personalizados e âncoras de texto.

Os links de referência do MkDocs são quaisquer links formatados da seguinte forma:

[Link text][link-target]

São necessárias âncoras personalizadas de cabeçalho e conteúdo

Qualquer cabeçalho ou seção de conteúdo que seja referenciada no conteúdo de texto por meio de um link de referência MkDocs na documentação do BeeWare deve ter uma âncora personalizada anexada. Caso contrário, há a possibilidade de quebrar os links quando o conteúdo do cabeçalho for traduzido.

Se precisar criar um link para uma âncora de cabeçalho, você precisará gerar uma âncora personalizada para o conteúdo pretendido. A sintaxe geral para definir uma âncora personalizada é a seguinte:

# Header text { #anchor-name }

Por exemplo, a personalização da âncora dessa seção para custom-anchors seria feita com a seguinte formatação:

## Custom Markdown anchors { #custom-anchors }

Você também pode criar uma âncora em conteúdo geral, incluindo texto e blocos de código. A formatação a seguir, com novas linhas acima e abaixo, deve ser incluída acima do conteúdo para o qual você deseja criar um link:

Content above.

[](){ #anchor-name }

Content below, that is now attached to the anchor above.

Depois que as âncoras personalizadas forem criadas, você poderá criar links para elas no mesmo documento ou em outras partes da documentação.

O Markdown padrão é usado para vincular a uma âncora no mesmo arquivo, que é formatada da seguinte forma:

[Link text](#anchor-name)

O link para uma âncora em um documento separado usa o estilo de link de referência do MkDocs, que é formatado da seguinte forma:

[Link text][anchor-name]

Links de referência da API¶

A vinculação de referência do MkDocs também oferece suporte à referência cruzada da documentação da API, incluindo classes documentadas, métodos ou atributos de classe e referências específicas de documentação externa.

Há várias opções para vincular a uma classe documentada ou a um método ou atributo de classe, independentemente de você estar vinculando a partir do mesmo arquivo ou de um arquivo separado. Ao criar links para classes, etc., você deve incluir reticências no primeiro conjunto de colchetes para renderizar o nome como código em linha. Os colchetes só não são necessários se você estiver usando texto personalizado que não deve ser renderizado como código em linha. Nunca se deve incluir pontos no segundo conjunto de colchetes.

O link para uma classe enquanto exibe o namespace é formatado da seguinte forma:

[`module.ClassName`][]

A vinculação a uma classe e a exibição apenas do nome da classe são formatadas da seguinte forma:

[`ClassName`][module.ClassName]

Os atributos são iguais aos anteriores, com o nome do atributo incluído. O seguinte exibe o namespace:

[`module.ClassName.attributename`][]

Assim como nas classes, a exibição apenas do nome do atributo é formatada da seguinte forma:

[`attributename`][module.ClassName.attributename]

Os métodos devem ser exibidos com () após o namespace e, portanto, devem ser tratados de forma diferente dos atributos. A seguir, a maneira apropriada de criar um link para um método:

[`module.ClassName.methodname()`][module.ClassName.methodname]

O seguinte exibe apenas o nome da classe e do método. Isso também requer a inclusão dos parênteses após o nome:

[`Classname.methodname()`][module.Classname.methodname]

Você pode criar um link para uma classe, um método ou um atributo enquanto exibe um texto arbitrário, usando o mesmo método com o namespace aplicável. Fazer isso com uma classe é formatado da seguinte forma:

[link text][module.ClassName]

Também é possível vincular-se diretamente à documentação principal do Python, bem como à documentação do Pillow. Por exemplo, para criar um link para a documentação de int:

[`int`][]

Para criar um link para a documentação do Pillow Image:

[`PIL.Image.Image`][]

Dicas de blocos de código¶

Destaque de linguagem e código¶

Você pode especificar o idioma para o código contido no bloco de código incluindo o nome do idioma após os três primeiros backticks, sem espaço entre eles. Isso resulta em um destaque de código apropriado quando o código é renderizado. Por exemplo, para especificar Python, você iniciaria o bloco de código com `python.

Comandos do console e o botão de cópia¶

Se estiver incluindo comandos de console ou comandos com saída, rotule-os como console ou doscon, dependendo se estiver descrevendo um sistema operacional do tipo Unix (incluindo macOS) ou Windows. Você pode incluir o prompt fornecido pelo sistema operacional; somente o comando será copiado quando você clicar no botão de cópia. Por exemplo, se você iniciar um bloco de código com ``console e incluir o seguinte conteúdo:

$ mkdir test
$ ls
test

Em seguida, clicar no botão de cópia no bloco de código copiará apenas os comandos e ignorará os prompts e a saída. Isso permite indicar que são comandos do console e, ao mesmo tempo, permite que os usuários usem o botão de cópia de forma eficaz.

Destaque de linhas específicas de código¶

Você pode destacar linhas específicas de código. Por exemplo, para destacar a linha 2, você adicionaria um espaço após a linguagem, seguido de {hl_lines="2"}. Portanto, seu bloco de código começaria com ```python {hl_lines="2"}. O resultado é:

import toga
from toga.style.pack import COLUMN, ROW

Você pode destacar várias linhas diferentes. Por exemplo, python {hl_lines="3 5 9"} destacaria as linhas 3, 5 e 9. Você também pode destacar um intervalo de linhas. Por exemplo, python {hl_lines="3-8"} destaca as linhas 3 a 8. Você pode destacar vários intervalos com, por exemplo, python {hl_lines="9-18 23-44"}.

Elementos Markdown que exigem formatação específica¶

Devido à forma como os arquivos de tradução são gerados, é importante incluir as novas linhas necessárias na sintaxe Markdown para advertências, notas, guias, diretivas Jinja, legendas e alinhamento de imagens, etc.

Admoestações e notas¶

As admoestações devem ser formatadas da seguinte forma, incluindo a garantia de uma nova linha antes e depois do início e do fim da admoestação:

Content above.

/// admonition | Title

Admonition text.

A second paragraph.

///

Content below.

Isso funciona da mesma maneira com qualquer tipo de advertência suportado. Por exemplo, as advertências de nota exigem a mesma formatação e novas linhas:

Content above.

/// note | Note title

Note text here.

///

Content below.

Todos os tipos de advertências suportados estão disponíveis para uso como advertências.

Conteúdo com guias¶

O conteúdo com guias é formatado da seguinte forma, incluindo uma nova linha antes do início e depois do fim do bloco de conteúdo:

Content above.

/// tab | Tab one title

Tab one text

///

/// tab | Tab two title

Tab two text.

///

/// tab | Tab three title

Tab three text.

///

Content below.

Uma tabulação com uma advertência aninhada seria formatada da seguinte forma, incluindo uma nova linha antes e depois do bloco de conteúdo:

Content above.

/// tab | Windows

Tab text.

/// admonition | Admonition

Admonition text.

///

///

Content below.

Conteúdo recolhido¶

O conteúdo recolhido é formatado da seguinte forma, incluindo novas linhas:

Content above.

/// details-note | Collapsed content title

Collapsed content.

///

Content below.

Todos os tipos de advertência suportados estão disponíveis para uso com conteúdo recolhido, no entanto, você deve declará-los como details-admonitiontype. Assim, um bloco recolhido do tipo “nota” seria details-note (como mostrado acima), um bloco recolhido do tipo “aviso” seria details-warning, e assim por diante.

Diretrizes Jinja¶

Há alguns recursos da documentação que usam as diretivas Jinja no texto. Qualquer coisa que use os recursos da diretiva Jinja precisa ser envolvida em novas linhas. Por exemplo, o tutorial do BeeWare contém condicionais Jinja baseadas em variáveis para determinar qual advertência mostrar na página principal. Elas são formatadas da seguinte forma:

Content above.



Content below.

Há também uma sintaxe para substituir símbolos ou texto. Essa sintaxe é uma variável envolvida em um par de chaves duplas correspondentes e, se estiver em sua própria linha, deve incluir uma nova linha antes e depois.

Content above.

{{ variable }}

Content below.

Formatação de imagens¶

As imagens podem ter a largura definida e podem ser alinhadas à esquerda, à direita e ao centro (com uma ressalva quanto ao "centro"). As imagens devem sempre incluir um texto alternativo significativo para fins de acessibilidade.

A definição da largura de 300px em uma imagem seria formatada da seguinte forma:

![Image alt text](../path/to/image.png){ width="300px" }

O alinhamento de uma imagem à esquerda (ou à direita) seria formatado da seguinte forma:

![Image alt text](../path/to/image.png){ align=left }

A adição de uma legenda a uma imagem requer uma nova linha antes e depois, e é formatada da seguinte forma:

Content above.

![Image alt text](/path/to/image.png)

/// caption

Caption content.

///

Content below.

O alinhamento central de uma imagem não é possível com o atributo align. A solução alternativa é seguir a imagem com uma legenda vazia, e ela será centralizada. Você deve incluir novas linhas entre cada seção, antes e depois. Ele é formatado da seguinte forma:

Content above.

![Image alt text](../path/to/image.png)

/// caption

///

Content below.

Plug-ins com formatação Markdown específica¶

As seções a seguir abordam como utilizar plug-ins que exigem formatação Markdown específica.

Uso de snippets para incluir conteúdo externo¶

Para obter detalhes sobre como incluir conteúdo externo de um arquivo local ou de um URL, consulte a Snippets extension documentation. O Snippets deve ser usado desde que o documento não contenha diretivas Jinja que precisem ser executadas (a execução do Jinja ocorre juntamente com o processamento do Snippets e, portanto, qualquer Jinja no arquivo não será processado). O Snippets é necessário se você quiser usar delimitadores que permitam incluir partes específicas de um arquivo separadamente, por exemplo, o documento de origem é dividido em seções a serem injetadas separadamente umas das outras.

Observações importantes:

Usamos -8<- como identificador de Snippets. A documentação mostra várias opções; siga nosso estilo.
Os arquivos encontrados no conteúdo compartilhado do BeeWare Docs Tools são tratados como conteúdo "local". Portanto, você usará apenas o nome do arquivo, como em -8<- "docs-style-guide.md", ou, se o conteúdo estiver em um subdiretório, apenas o diretório e o nome do arquivo, como em -8<- "style/docs-style-guide.md".
Se estiver incluindo conteúdo externo de um arquivo no GitHub por meio de um URL, você deve usar o URL do conteúdo bruto, ou ele renderizará a página da Web completa incorporada onde quer que você a inclua.

Uso de macros para incluir conteúdo compartilhado do BeeWare Docs Tools¶

Você também pode incluir conteúdo do diretório de conteúdo compartilhado das ferramentas do BeeWare Docs usando o plugin Macros MkDocs. Esse método é necessário se o documento contiver diretivas Jinja que precisem ser executadas e só deve ser usado nessa situação. Ele não funcionará com conteúdo externo por meio de um URL. O mecanismo Macros variable-replacement mechanism funciona com esse método.

Há opções para incluir conteúdo usando macros:

Use a sintaxe include Jinja se quiser incluir o documento sem nenhuma outra alteração manual.
Use a sintaxe Jinja extends se tiver incluído a sintaxe Jinja block no documento, que permite substituir ou adicionar seções específicas.

`pyspelling`¶

Usamos o verificador ortográfico pyspelling. Ele é executado durante as verificações de lint.

Quando pyspelling identifica uma palavra com erro ortográfico, na maioria dos casos, ela deve ser corrigida no conteúdo da documentação.

Nos raros casos em que ele identifica uma palavra válida que não está no dicionário pyspelling, você tem duas opções:

Se for uma palavra que provavelmente será reutilizada várias vezes, você deverá adicioná-la ao documento spelling_wordlist no diretório docs, em ordem alfabética.
Se for uma palavra que provavelmente não será usada novamente, você poderá envolvê-la em uma tag <nospell> / </nospell>, e o pyspelling a ignorará inline.