Arquivos de uso

Cada página de utilitário mostra a spec, a assinatura e os casos de teste do contrato no docs. Os exemplos de código nas abas vêm das bibliotecas. Cada biblioteca escreve os próprios exemplos, no próprio repositório. Quem muda a API atualiza os exemplos no mesmo pull request. Este site só lê.

Uma biblioteca pode publicar os exemplos de três formas, que podem ser combinadas:

Arquivos de uso

python/
└── docs/
    └── usage/
        ├── cpf.md
        ├── cnpj.md
        ├── license-plate.md
        └── …

Escreva um arquivo para cada utilitário. Dê ao arquivo o nome da página, em kebab-case (cpf.md, license-plate.md). No arquivo, escreva um título ## para cada função. O título é o nome da função no contrato, que é uma chave de functions em contract/<domínio>/contract.json:

## isValid

```python
from brutils import is_valid_cpf

is_valid_cpf('82178537464')  # True
is_valid_cpf('00011122233')  # False
```

## format

```python
from brutils import format_cpf

format_cpf('82178537464')  # '821.785.374-64'
```

Regras:

• O título é o nome da função: isValid, format, parse, generate, getInfo. O site também aceita get-info, o título padrão (Validate) e o nome antigo validate. O docs usage aponta um título que não corresponde a nenhuma função, e o build o ignora.
• Cada seção mostra a chamada. Mostre o import, a chamada e o resultado. Uma linha de texto pode ajudar, por exemplo "Esta função chama o ViaCEP". Não explique a regra. A spec na mesma página explica.
• O exemplo chama a função da biblioteca. O validador sabe o nome nativo de cada função. O validador aponta uma seção que não usa esse nome.
• Escreva código e comentários em inglês. Para texto em português, adicione cpf.pt-br.md ao lado de cpf.md. As páginas em português usam esse arquivo.
• since é opcional. Coloque since: 2.1.0 no front matter para mostrar a primeira versão com o utilitário.
• Uma função sem seção tem a aba vazia. A aba então diz que a biblioteca não tem a função, ou que tem a função mas não tem exemplo.

Página de referência

Muitas bibliotecas já documentam todas as funções numa página só, com um título para cada função. Essa página serve do jeito que está. Declare a página em libs/<lib>.json:

"usage": {
  "ref": "main",
  "reference": { "en": "docs/utilities.md", "pt-BR": "docs/pt-br/utilities.md" }
}

O site encontra cada título que é um nome de função da biblioteca, como ### isValidCpf. O site liga esse título à função do contrato que o validador associou ao nome. Uma seção é todo o texto até o próximo título: texto, opções, casos de borda e exemplos. O site ignora outros títulos, como ## Conventions ou ## CPF. O texto antes da primeira função vai para a página da biblioteca, como convenções da API.

Se uma biblioteca tem os dois, os arquivos de uso têm prioridade nas funções que eles documentam. docs usage --lib <lib> --materialize converte uma página de referência em arquivos de uso. Use o comando para passar uma biblioteca para arquivos de uso, ou para atualizar a cópia offline do site.

Guias com exemplos interativos

Algumas tarefas precisam de mais de uma chamada: um campo que aplica máscara e valida enquanto você digita, um formulário de endereço que o CEP preenche, uma lista de estados e cidades. Quem faz front-end precisa ver isso funcionando. Uma biblioteca pode publicar guias, que são páginas Markdown com exemplos em abas. Existe uma aba para cada framework, uma segunda fileira de abas para cada variante, e uma aba para cada arquivo. Cada exemplo pode ter uma versão interativa.

"usage": {
  "guides": { "en": "docs/guides", "pt-BR": "docs/pt-br/guides" },
  "root": "docs",
  "assets": ["docs/snippets"],
  "prepare": ["node", "scripts/examples.ts"]
}

O front matter de um guia dá o title e a description dele. Os guias de uma biblioteca seguem a ordem dos nomes de arquivo. Um guia com order: 1 no front matter vai depois dos outros, e um com order: -1 vai antes deles.

Num guia, marque cada exemplo com estas tags. Coloque cada tag numa linha própria. O docsify também entende essa marcação, então uma biblioteca pode usar os mesmos arquivos no próprio site.

<div class="example" data-name="React">

Texto sobre a versão React.

<div class="variant" data-variant="CPF" data-demo="/snippets/live/?dir=cpf/react&example=cpf-field.tsx">

<div class="file" data-file="cpf-field.tsx">

[cpf-field.tsx](../snippets/cpf/react/cpf-field.tsx ':include :type=code tsx')

</div>

</div>

</div>

• example é uma aba de framework (React, Angular, Vue, Vanilla) ou de biblioteca (Zod, Valibot). O leitor escolhe uma aba uma vez, e todo guia abre nessa aba.
• variant é uma segunda fileira de abas, opcional, por exemplo CPF, CNPJ, CEP e Telefone.
• file é um arquivo do exemplo. Use um link :include para o arquivo no repositório, ou um bloco de código.
• data-demo é uma página da biblioteca que roda o exemplo. O caminho começa em root. O site mostra a versão interativa acima dos arquivos. O site copia as pastas de assets sem mudanças, então a versão interativa roda o mesmo código que a página mostra. A página envia a própria altura com parent.postMessage({ type: 'example-height', height }, location.origin).
• prepare é um comando que o site roda nos arquivos da biblioteca antes de ler esses arquivos. Use quando a biblioteca gera os próprios exemplos. O comando roda sem shell e sem segredos.

Links entre guias ficam neste site. Um link para a página de referência com âncora de função, como utilities.md#formatcpf, vai para aquela função neste site. O site encontra as funções do contrato que cada guia chama, e lista o guia nas páginas desses utilitários.

Teste com JavaScript

Cada função da biblioteca JavaScript ganha uma caixa Teste com JavaScript. O site gera essa caixa a partir do contrato. Ela tem uma entrada para cada parâmetro do contrato, com o primeiro caso de teste compartilhado como valor inicial. Ela roda o pacote JavaScript publicado no navegador. Se as entradas forem as de um caso de teste compartilhado, a caixa diz se o resultado é o que o contrato espera.

Gere os primeiros exemplos

Você não precisa escrever os primeiros exemplos à mão. O validador sabe quais funções a biblioteca implementa e em quais casos de teste compartilhados ela passa. A partir desses casos, ele escreve uma seção para cada função sem exemplo, na linguagem da biblioteca:

# no repositório da biblioteca, depois do `check --tests` gerar o relatório
npx tsx <docs>/src/cli.ts check --lib python --path . --tests
npx tsx <docs>/src/cli.ts usage --lib python --path . --scaffold

O comando não muda seções que existem e adiciona as seções novas no fim do arquivo. O resultado em cada comentário é o valor que o contrato espera, tirado de um caso que já passa na biblioteca. Os exemplos estão corretos quando o comando os escreve. Você pode editar depois.

Sem --scaffold, o docs usage mostra o que está documentado, o que falta e o que está errado. Com --strict, o comando falha quando falta algo ou algo está errado. Uma biblioteca pode usar isso na CI.

A versão no site

O site lê os arquivos em usage.ref. O padrão é a última release no GitHub da biblioteca, então o site bate com o pacote que o leitor instala. Um repositório sem release usa a branch padrão. Se a documentação da própria biblioteca segue a branch principal, use "ref": "main".

Uma biblioteca sem docs/usage/ usa as cópias em site/fixtures/usage/<lib>/ do repositório docs. Essas cópias têm o mesmo formato, então você pode copiá-las para a biblioteca do jeito que estão.

Atualize o site a cada release

Adicione este passo ao workflow de release da biblioteca. O site então é gerado de novo com a versão nova:

- name: Notify the docs site
  if: success()
  run: gh api repos/brazilian-utils/docs/dispatches -f event_type=lib-released -f 'client_payload[lib]=python'
  env:
    GH_TOKEN: ${{ secrets.DOCS_DISPATCH_TOKEN }}

Sem esse passo, o site é gerado de novo todo dia e depois de cada mudança no contrato.

Adicione arquivos de uso a uma biblioteca