Verificar sua documentação usando o Vale
Antes de criar uma solicitação de mesclagem para qualquer documentação ou atualização de documentação, você precisará executar Vale no seu texto.
Vale é uma ferramenta de linha de comando que verifica a aderência do seu texto a um guia de estilo definido. A documentação do Fedora usa o guia de estilo da Red Hat.
Instale o Vale no seu computador
Você pode instalar o Vale no seu computador ou usar uma versão conteinerizada com o Podman.
Para instalar o Vale em seu computador utilize um dos instaladores disponíveis para Windows, macOS e Linux.
Se você estiver usando o Fedora, você pode instalar a partir do repositório Copr mczernek/vale. Esteja ciente de que o Copr não é oficialmente suportado pela infraestrutura do Fedora. Use pacotes por sua conta e risco.
$ sudo dnf copr enable mczernek/vale && sudo dnf install vale
Você pode usar a versão conteinerizada do Vale se não quiser instalá-la localmente.
podman run --rm -v ${PWD}:/docs -w /docs jdkato/vale:latest <seu_arquivo.adoc>
Se você instalou o Vale localmente, verifique se o Vale está disponível usando o comando vale -v:
$ vale -v vale version 2.21.2 (sua versão pode ser diferente dependendo de quando você instalou o Vale)
O guia de estilo da Red Hat e os arquivos de configuração do Vale necessários já estão instalados e disponíveis no repositório que você fez fork na página principal do Fedora Docs no GitLab.
Você pode verificar isso procurando um arquivo .vale.ini na lista de arquivos do seu fork na sua conta do GitLab. Você não precisa baixar ou instalar nenhum arquivo de estilo adicional.
Usar o Vale para verificar arquivos ou diretórios
Para usar o Vale, faça o seguinte:
-
Crie ou edite um arquivo em seu repositório local do Fedora Docs. Veja Como criar e usar um ambiente de autoria local do Fedora para obter instruções sobre como bifurcar, clonar e gerenciar repositórios Git em seu computador.
-
Execute o linter Vale no arquivo. Você pode executar o Vale em um único arquivo, em vários arquivos e diretórios.
-
Faça atualizações no arquivo para corrigir erros, avisos ou sugestões.
-
Execute novamente o linter Vale para verificar se o arquivo passa.
Quando seu arquivo passar você poderá enviar seu trabalho e enviá-lo para seu fork no GitLab e abrir uma solicitação de mesclagem.
Comandos e saída do Vale
Para executar o Vale em um único arquivo:
$ vale nome-do-arquivo
Para executar o Vale em vários arquivos:
$ vale nome-de-arquivo 1 nome-de-arquivo 2
Para executar Vale em todos os arquivos em um diretório:
$ vale nome-diretório/
Vale retornará uma lista de resultados mostrando a localização no arquivo, o nível de severidade, uma dica sobre como corrigir o resultado e qual referência de estilo sinalizou o resultado. Por exemplo:
11:1 suggestion Define acronyms and RedHat.Definitions
abbreviations (such as 'TOC')
on first occurrence if they're
likely to be unfamiliar.
15:54 error Use 'for example' rather than RedHat.TermsErrors
'e.g.'.
15:59 warning Use correct American English RedHat.Spelling
spelling. Did you really mean
'Quickdocs'?
Se um arquivo retorna uma lista longa de resultados, use:
$ vale --no-wrap nome-de-arquivo
Isso imprimirá cada resultado em uma linha. Isso também é útil ao verificar muitos arquivos ou todos os arquivos em um diretório.
O Vale possui três níveis de resultados que listará na parte inferior do resultado: erro, aviso e sugestão.
✖ 1 error, 3 warnings and 4 suggestions in 1 file.
-
error: Este é um elemento bloqueante, e você deve corrigir quaisquer erros encontrados no arquivo.
-
warning: Isso não é um elemento bloqueante, mas é algo que você precisa corrigir para entrar em conformidade com o guia de estilo da Red Hat.
-
suggestion: Isso não é um elemento bloqueante, mas é algo que você precisa corrigir para entrar em conformidade com o guia de estilo da Red Hat.
Se você quiser procurar apenas um resultado específico, use o sinalizador --minAlertLevel nível. Isso é útil se você tiver uma longa lista de resultados e quiser trabalhar em um nível de resultado específico por vez.
--minAlertLevel suggestion (mostra sugestão, aviso e erro)
--minAlertLevel warning (mostra aviso e erro)
--minAlertLevel error (mostra apenas erro)
Por exemplo, para só mostrar resultados sinalizados com erro no arquivo, use:
$ vale --no-wrap --minAlertLevel error nome-de-arquivo
Como interpretar os resultados do Vale
Vale mostra os resultados por número de linha e posição (às vezes chamada de coluna). Também mostra a diretriz de estilo que sinalizou o conteúdo.
For example, this error is on line 15, starting at position 54
15:54 error Use 'for example' rather than 'e.g.'. RedHat.TermsErrors
15 ** Editor in chief for specific documentation areas, e.g. Quickdocs
^ position 54
Verify that your text editor shows line numbers and position. Most text editors will have a way to enable this view.
Vale will usually tell you exactly what you need to do to fix the line, which in this case is to use 'for example' instead of 'e.g.'
Rerun Vale to verify that the error is now resolved. Continue running Vale to clear all errors, warnings, and suggestions.
How to find guidance for correcting Vale results
Every result returned by Vale shows the Red Hat style reference that flagged the word or phrase. This is at the end of the each result, in the format of RedHat.style_name.
These files are in a .vale directory at the top level of your local repository, in a styles/RedHat subdirectory.
All the style files point back to the reference guide maintained by Red Hat on the Vale for writers at Red Hat page.
You can usually find guidance there on what to change to resolve any error or warning level results.
If you want to see the contents of a specific style file, you can examine the vale-at-red-hat page on GitHub.
If you still have questions or need help deciding what changes to make, post a question in the Fedora Documentation room on Fedora Chat.
More information
Vale documentation: https://vale.sh/docs/
Red Hat Technical Writing Style Guide: https://stylepedia.net/
Guidelines for Red Hat Documentation: https://redhat-documentation.github.io/
Fedora Docs Style Guide: https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/style-guide/
This guide shows how to use Vale from the command line, but plugins or packages are available for several common text editors.
Want to help? Learn how to contribute to Fedora Docs ›