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 iniciada em maiúscula (capitalizada).
- Preferimos a ortografia dos EUA, com algumas liberdades para as expressões coloquiais específicas da programação (por exemplo, "apps") e a verbalização de substantivos (por exemplo, "scrollable").
- A ortografia de "artefact" e "artefacts" é como mostrada.
- Usamos um espaço único após um ponto final.
- Usamos um único hífen rodeado por espaços como travessão (ou um
—de HTML). - Qualquer referência a um nome de produto deve usar a capitalização preferencial do produto. (ex.,
"macOS", "GTK", "pytest", "Pygame", "PyScript" ). - Se um termo estiver a ser usado "como código", ele deve ser citado como código embutido, envolvendo-o com aspas invertidas únicas, em vez de ser adicionado ao dicionário.
- Evitamos usar termos como “simplesmente”, “apenas” ou “facilmente” ao descrever ações que o utilizador deve realizar. Esses termos podem ser interpretados como pejorativos, especialmente quando um utilizador está a enfrentar dificuldades.
Informações de referência cruzada¶
Deve fazer referência cruzada ao conteúdo da documentação sempre que possível. Esta secção aborda as várias maneiras de fazer isso, cada uma delas baseada no tipo de informação que está a ser referenciada.
O MkDocs renderiza atalhos formatados em norma Markdown. Os hiperlinks Web com formatação Markdown standard são os seguintes:
[Texto do link](https://example.com/)
Também pode usar esse formato para vincular a um ficheiro local:
[Texto do link](caminho/para/ficheiro.md)
Para fazer referência a secções específicas de ficheiros ou à documentação da API, é necessário usar o formato de atalho 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 secção é custom-markdown-anchors-and-content-cross---referencing. No entanto, devido à maneira como as nossas traduções funcionam, sempre que um cabeçalho de secção for referenciado, ele deve ter uma âncora personalizada.
O MkDocs suporta a renderização de sintaxe de link de referência que permite que 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:
[Texto do link][alvo-do-link]
São obrigatórias âncoras personalizadas de cabeçalho e conteúdo
Qualquer cabeçalho ou secçã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 tem de 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, vai precisar gerar uma âncora personalizada para o conteúdo pretendido. A sintaxe geral para definir uma âncora personalizada é a seguinte:
# Texto do cabeçalho { #nome-da-âncora }
Por exemplo, a personalização da âncora dessa secção para custom-anchors seria feita com o seguinte formato:
## Âncoras personalizadas do Markdown { #custom-anchors }
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 deseja criar um atalho:
Conteúdo em cima.
[](){ #nome-da-âncora }
Conteúdo em baixo, que agora está vinculado à âncora em cima.
Depois que as âncoras personalizadas serem criadas, pode criar links para elas no mesmo documento, ou noutras partes da documentação.
O Markdown standard é usado para vincular a uma âncora no mesmo ficheiro, que é formatada da seguinte forma:
[Texto do link](#nome-de-âncora)
O link para uma âncora num documento separado usa o estilo de link de referência do MkDocs, que é formatado da seguinte forma:
[Texto do link][nome-da-âncora]
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 estar a vincular a partir do mesmo ficheiro ou de um ficheiro separado. Ao criar links para classes, etc., deve incluir aspas invertidas no primeiro conjunto de parênteses retos para renderizar o nome como código em linha. As aspas só não são necessárias se estiver a usar texto personalizado que não deve ser renderizado como código em linha. Nunca se deve incluir pontos no segundo conjunto de parênteses retos.
O link para uma classe enquanto mostra o espaço de nome é formatado da seguinte forma:
[`modulo.NomeClasse`][]
A vinculação a uma classe enquanto se mostra apenas do nome da classe é formatada da seguinte forma:
[`NomeClasse`][modulo.NomeClasse]
Os atributos são o mesmo que em cima, com o nome do atributo incluído. O seguinte mostra o espaço de nome:
[`modulo.NomeClasse.nomeatributo`][]
Como nas classes, a exibição apenas do nome do atributo é formatada da seguinte forma:
[`nomeatributo`][modulo.NomeClasse.nomeatributo]
Os métodos devem ser mostrados com () após o espaço de nome, e portanto, devem ser tratados de forma diferente dos atributos. A seguir, a maneira apropriada de criar um link para um método:
[`modulo.NomeClasse.nomemétodo()`][modulo.NomeClasse.nomemétodo]
O seguinte mostra apenas o nome da classe e do método. Isso também requer a inclusão dos parênteses após o nome:
[`Nomeclasse.nomemétodo()`][modulo.Nomeclasse.nomemétodo]
Pode criar um link para uma classe, um método ou um atributo enquanto mostra um texto arbitrário, usando o mesmo método com o espaço de nome aplicável. Fazer isso com uma classe é formatado da seguinte forma:
[texto do link][modulo.NomeClasse]
Também é possível vincular 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¶
Pode especificar a linguagem para o código contido no bloco de código incluindo o nome da linguagem após as três primeiras aspas, sem espaço entre elas. Isso resulta num destaque de código apropriado quando o código é renderizado. Por exemplo, para especificar Python, iniciaria o bloco de código com ```python.
Comandos da consola e o botão de copiar¶
Se estiver a incluir comandos de consola ou comandos com saída, se os etiquetar como console ou doscon, dependendo se estiver a descrever um sistema operativo do tipo Unix (incluindo macOS) ou Windows. Pode incluir o aviso fornecido pelo sistema operativo; apenas o comando será copiado quando clicar no botão de cópia. Por exemplo, se iniciar um bloco de código com ```console e incluir o seguinte conteúdo:
$ mkdir test
$ ls
test
Depois, clicar no botão de cópia no bloco de código vai copiar apenas os comandos e ignorar os avisos e resultados. Isso permite indicar que são comandos da consola e, ao mesmo tempo, permite que os utilizadores usem o botão de cópia de forma eficaz.
Destacar linhas específicas de código¶
Pode destacar linhas específicas de código. Por exemplo, para destacar a linha 2, adicione um espaço após a linguagem, seguido de {hl_lines="2"}. Assim, o seu bloco de código começa com ```python {hl_lines="2"}. O resultado é:
import toga
from toga.style.pack import COLUMN, ROW
Pode destacar várias linhas diferentes. Por exemplo, python {hl_lines="3 5 9"} destaca as linhas 3, 5 e 9. Também pode destacar um intervalo de linhas. Por exemplo, python {hl_lines="3-8"} destaca as linhas 3 a 8. 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 ficheiros 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.
Advertências e notas¶
As advertências devem ser formatadas da seguinte forma, incluindo a garantia de uma nova linha antes e depois do início e fim da advertência:
Conteúdo em cima.
/// admonition | Título
Texto da advertência.
Um segundo parágrafo.
///
Conteúdo em baixo.
Isso funciona da mesma maneira com qualquer tipo de advertência suportada. Por exemplo, as advertências de nota exigem a mesma formatação e novas linhas:
Conteúdo em cima.
/// note | Título da nota
Texto da nota aqui.
///
Conteúdo em baixo.
Todos os tipos de advertências suportados estão disponíveis para uso como advertências.
Conteúdo com separadores¶
O conteúdo com separadores é formatado da seguinte forma, incluindo uma nova linha antes do início e depois do fim do bloco de conteúdo:
Conteúdo em cima.
/// tab | Título do separador um
Texto do separador um
///
/// tab | Título do separador dois
Texto do separador dois.
///
/// tab | Título do separador três
Texto do separador três.
///
Conteúdo em baixo.
Um separador com uma advertência aninhada seria formatado da seguinte forma, incluindo uma nova linha antes e depois do bloco de conteúdo:
Conteúdo em cima.
/// tab | Windows
Texto do separador.
/// admonition | Advertência
Texto da advertência.
///
///
Conteúdo em baixo.
Conteúdo recolhido¶
O conteúdo recolhido é formatado da seguinte forma, incluindo novas linhas:
Conteúdo em cima.
/// details-note | Título do conteúdo recolhido
Conteúdo recolhido.
///
Conteúdo em baixo.
Todos os tipos de advertência suportados estão disponíveis para uso com conteúdo recolhido, no entanto, deve declara-los como details-admonitiontype. Assim, um bloco recolhido do tipo “note” seria details-note (como mostrado em cima), um bloco recolhido do tipo “warning” 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:
Conteúdo em cima.
Conteúdo em baixo.
Há também uma sintaxe para substituir símbolos ou texto. Essa sintaxe é uma variável envolvida num par de chavetas duplas correspondentes e, se estiver em sua própria linha, deve incluir uma nova linha antes e depois.
Conteúdo em cima.
{{ variável }}
Conteúdo em baixo.
Formatar 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
{ width="300px" }
O alinhamento de uma imagem à esquerda (ou à direita) seria formatado da seguinte forma:
{ align=left }
Adicionar uma legenda a uma imagem requer uma nova linha antes e depois, e é formatada da seguinte forma:
Conteúdo em cima.
/// caption
Conteúdo da legenda.
///
Conteúdo em baixo.
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á centrada. Deve incluir novas linhas entre cada secção, antes e depois. É formatado da seguinte forma:
Conteúdo em cima.
/// caption
///
Conteúdo em baixo.
Plugins com formatação Markdown específica¶
As secções a seguir abordam como utilizar plugins que exigem formatação Markdown específica.
Uso de Trechos para incluir conteúdo externo¶
Para obter detalhes sobre como incluir conteúdo externo de um ficheiro local ou de um URL, consulte a Documentação de extensão de Trechos. O Trecho 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 Trecho e, portanto, qualquer Jinja no ficheiro não será processado). O Trecho é necessário se quiser usar delimitadores que permitam incluir partes específicas de um ficheiro separadamente, por exemplo, o documento de origem é dividido em secções a serem injetadas separadamente umas das outras.
Notas importantes:
- Usamos
-8<-como identificador de Trechos. A documentação mostra várias opções; por favor siga o nosso estilo. - Os ficheiros encontrados no conteúdo partilhado do BeeWare Docs Tools são tratados como conteúdo "local". Portanto, use apenas o nome do ficheiro, 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 ficheiro, como em-8<- "style/docs-style-guide.md". - Se estiver incluindo conteúdo externo de um ficheiro no GitHub por meio de um URL, tem de usar o URL do conteúdo bruto, ou ele vai renderizar a página Web completa incorporada onde quer que a inclua.
Usar de macros para incluir conteúdo partilhado do BeeWare Docs Tools¶
Também pode incluir conteúdo do diretório de conteúdo partilhado das ferramentas do BeeWare Docs usando o plugin Macros MkDocs. Este método é necessário se o documento conter diretivas Jinja que precisem ser executadas e só deve ser usado nessa situação. Ele não vai funcionar com conteúdo externo por meio de um URL. O mecanismo Macros variable-replacement mechanism funciona com este método.
Existem opções para incluir conteúdo usando Macros:
-
Use a sintaxe
includeJinja se quiser incluir o documento sem nenhuma outra alteração manual. -
Use a sintaxe Jinja
extendsse tiver incluído a sintaxe Jinjablockno documento, que permite substituir ou adicionar secções específicas.
pyspelling¶
Usamos o verificador ortográfico pyspelling. É 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, tem duas opções:
- Se for uma palavra que provavelmente será reutilizada várias vezes, deve adiciona-la ao documento
spelling_wordlistno diretóriodocs, em ordem alfabética. - Se for uma palavra que provavelmente não será usada novamente, pode envolve-la numa etiqueta
<nospell>/</nospell>, e opyspellinga vai ignorar inline.