Manter um livro de documentação cujos exemplos de código são testados como código real

## Tratar cada bloco de código do livro como código testado, não só como texto O livro é uma coleção de exemplos práticos escritos como arquivos markdown com blocos de código embutidos. Um harness de doc-test percorre a árvore de fontes, extrai cada bloco de código, compila-o e o executa, de modo que um exemplo quebrado faz o build falhar exatamente como um código de aplicação quebrado. ### O que isso implica para cada edição Um exemplo que não compila não é documentação. A prosa pode ser reescrita livremente, mas qualquer alteração dentro de um bloco de código é uma alteração em código-fonte testado e precisa passar pelo comando de teste antes de ser proposta. ### Mantenha o livro renderizado e a superfície de teste em sincronia O mesmo markdown alimenta o livro renderizado e o harness de teste, portanto as escolhas de formatação carregam semântica. As anotações de um bloco de código decidem como o harness o trata, e as linhas ocultas dos leitores continuam sendo compiladas. Nunca remova uma anotação ou uma linha oculta apenas para deixar a página renderizada mais limpa. ## Compilar, testar e ver o livro com os comandos documentados Encaminhe toda ação rotineira pelos comandos documentados, em vez de inventar invocações improvisadas, para que as execuções locais correspondam à integração contínua. ### Os comandos que importam - Gerar o livro a partir das fontes markdown. - Executar a suíte completa, que são os doc tests mais a etapa de verificação ortográfica. - Executar apenas o alvo de doc-test quando você alterou um bloco de código e quer o ciclo rápido. - Servir o livro localmente com recarga ao vivo enquanto edita a prosa. - Fazer build e testes juntos como padrão antes da revisão. - Executar o verificador de links, que valida links internos e externos contra um arquivo de configuração versionado no repositório. - Executar o script de verificação ortográfica de forma interativa e adicionar as palavras novas legítimas ao arquivo de dicionário do repositório, para que a adição seja revisada junto com a mudança. ### Fixe a toolchain O gerador do livro e o verificador de links são instalados em versões exatas e fixadas, a partir de um único comando de instalação documentado. Não atualize uma ferramenta localmente para contornar uma falha, porque uma divergência de versão transforma uma falha reproduzível em uma falha que só você consegue ver. ## Conhecer as duas formas de guardar exemplos e não subir versões de bibliotecas compartilhadas Os exemplos são testados de uma entre duas maneiras, e saber qual padrão um arquivo usa determina onde ficam o seu código e as suas dependências. ### Padrão um: blocos inline testados no lugar Os blocos de código ficam diretamente no markdown, sob a árvore de fontes. Um script de build percorre essa árvore em busca de arquivos markdown e gera um teste por bloco de código. Toda dependência de que um exemplo desses precise já deve existir no manifesto raiz. Os blocos aceitam anotações para a edição da linguagem e para comportamentos como somente-compilar, pânico-esperado e pular; o código repetitivo que os leitores não precisam ver é escrito como linhas prefixadas por um cerquilha e um espaço, que o harness compila mas o livro renderizado esconde. Este é o padrão legado, mantido funcionando, porém não estendido. ### Padrão dois: pacotes autônomos incluídos no markdown O código fica em seu próprio pacote, sob um diretório de código compartilhado, com um manifesto independente, e o markdown o puxa por meio de uma diretiva de include que aponta para o arquivo-fonte por caminho relativo. Includes por intervalo de linhas permitem que uma página mostre apenas parte de um arquivo, que é como o andaime de teste é mantido fora do exemplo renderizado. O caminho é excluído do harness de doc-test no script de build, para que o código não seja testado duas vezes. Este é o padrão preferido para exemplos novos e migrados. ### A regra das dependências Não altere versões de dependências no manifesto raiz. O manifesto raiz é compartilhado por todos os exemplos inline, então subir uma versão para atender a uma página pode quebrar dezenas de outras silenciosamente. Quando um exemplo precisa de uma dependência mais nova, migre esse exemplo para um pacote autônomo com suas próprias versões fixadas. ## Levar para um pacote próprio o exemplo que precisa de uma biblioteca mais nova Quando uma versão de dependência precisar mudar, converta os exemplos afetados em pacotes autônomos. Siga os passos na ordem, porque cada um deixa o repositório em um estado do qual o passo seguinte depende. 1. Crie o pacote sob o diretório de código compartilhado, em uma pasta nomeada pela sua categoria e depois pelo exemplo, com seu próprio manifesto. Herde as dependências compartilhadas do workspace quando possível, ou fixe versões de forma independente quando divergir for justamente o propósito. 2. Mova o código do bloco de código markdown para a fonte do pacote: um binário por exemplo executável, ou um módulo de biblioteca para exemplos em estilo de biblioteca. 3. Registre o pacote na lista de membros do workspace no manifesto raiz. 4. Substitua o código inline no markdown por uma diretiva de include cujo caminho relativo parta da própria localização do arquivo markdown até a fonte do pacote. 5. Exclua o caminho migrado do harness de doc-test no script de build. Existem duas listas de exclusão: uma que recebe um prefixo de diretório e remove tudo que está abaixo dele, e outra que recebe um único arquivo markdown. Use a mais estreita que servir. 6. Teste os dois lados: execute os testes do próprio pacote novo e reexecute o alvo de doc-test para confirmar que remover o bloco não quebrou os exemplos inline restantes. Uma migração que para antes do passo cinco deixa o exemplo compilado duas vezes, e uma que para antes do passo seis pode derrubar a cobertura silenciosamente. ## Ler os arquivos que decidem o que é compilado e testado Um punhado de arquivos decide o que é testado, o que é renderizado e quais comandos existem. Leia-os antes de mudar comportamento e altere-os de forma deliberada. - O manifesto raiz guarda as dependências usadas pelos exemplos inline e a lista de membros do workspace. - O script de build descobre o markdown para o harness de doc-test e carrega as duas listas de exclusão que impedem que exemplos migrados sejam testados duas vezes. - O arquivo de configuração do livro controla como o markdown é renderizado no livro. - A configuração da ferramenta de build define o alias do executor de tarefas do qual os comandos documentados dependem. - O pacote do executor de tarefas implementa build, testes e verificação de links como subcomandos, de modo que a mesma lógica sirva tanto a uma pessoa colaboradora quanto à integração contínua. Se um comando se comportar de forma diferente da descrição aqui, trate os arquivos acima como a fonte da verdade e corrija a descrição, em vez de contorná-la. ## Escrever exemplos completos que o leitor possa copiar e executar Um exemplo é julgado por conseguir ou não ser copiado para o projeto de outra pessoa e funcionar, não por quão curto ele parece na página. ### Regras de conteúdo - Os exemplos são completos e compiláveis, não fragmentos. - Propague erros com o operador de propagação de erros da linguagem, em vez de entrar em pânico na falha, e siga o padrão de tratamento de erros documentado do projeto. - Evite imports por glob, para que a pessoa leitora consiga ver exatamente de quais traits e itens o exemplo depende. - Marque como somente-compilar os exemplos que precisam de um serviço externo ou de acesso à rede, para que a suíte continue executável offline. - Esconda o código repetitivo com o prefixo de linha oculta em vez de apagá-lo, para que o exemplo continue compilando. - Prefira criar um pacote autônomo para um exemplo novo a adicionar mais uma dependência ao manifesto raiz. ### Adicionando uma nova seção de nível superior Quando adicionar uma página de seção de nível superior nova, adicione também um include dela na página de sumário do livro, na posição alfabética correta. Essa página é o ponto de entrada da pessoa leitora, e uma seção que não está incluída ali é, na prática, invisível, mesmo que compile com sucesso. ## Passar em todos os testes e na lista de verificação antes de pedir revisão Verifique tudo o que segue antes de abrir ou atualizar uma mudança para revisão, e novamente depois de qualquer reescrita. - A suíte de testes completa passa localmente, usando o comando documentado de todos os testes em vez de uma execução parcial. - Os commits estão esmagados em um só e rebaseados sobre o branch main mais recente. - A descrição contém uma cláusula correta de fechamento de issue, ou a cláusula é removida por completo quando não existe issue. Um número de issue errado é pior do que nenhum. - As listas não renderizadas estão em ordem alfabética: links, referências, identificadores e entradas de manifesto. A ordenação é o que mantém pequenos os diffs futuros. - Os links da documentação para páginas externas de referência de API usam o segmento de versão com curinga em vez de uma versão fixada, para que o link não apodreça no próximo release. - O exemplo usa o tratamento de erros padrão do projeto, sem atalho de pânico na falha. - Os identificadores de código na descrição são escritos como nomes entre crases, com hyperlink para suas páginas de referência por meio de definições de link no fim do arquivo. Depois de enviar, acompanhe a execução da integração contínua e corrija qualquer falha que ela reporte, em vez de deixar uma mudança vermelha aberta para alguém revisar e triar.