Padrão de Documentação — Quantilica¶
Este documento define o padrão de README adotado por todos os repositórios da organização. Novos pacotes e contribuições devem seguir este guia.
Regras Gerais¶
- Idioma: Todo o texto em prosa (descrições, títulos de seção, comentários) é escrito em português. Exemplos de código, flags de CLI, identificadores e nomes de funções permanecem em inglês.
- Emoji: Nenhum emoji decorativo em cabeçalhos ou prosa. Usar somente onde necessário para clareza técnica (ex: tabelas comparativas).
- Instalação: apenas
quantilica-coreequantilica-clisão publicados no PyPI e usampip install <pacote>/uv add <pacote>; os demais (ibge-sidra-fetcher,sidra-sql,bcb-sgs-sql, fetchers restantes, analytics, catalog) são instalados viaquantilica install <fonte>ou com--index https://index.quantilica.com/simple/.
Badges¶
Linha de badges imediatamente após o título #, seguindo o padrão flat-square:
 
- A versão Python deve corresponder ao
requires-pythondopyproject.toml. - Licença
MITpara todos os pacotes. - Badge de CI apenas em pacotes com workflow de testes ativo.
- Pacotes publicados no PyPI (apenas
quantilica-coreequantilica-cli) adicionam um badge de versão do PyPI:.
Voz narrativa (aberturas)¶
Páginas de domínio (*/index.md) e receitas do Cookbook abrem com narrativa; o resto da página segue referência técnica. O padrão tem três movimentos, em 2–4 frases:
- Cena — segunda pessoa, artefato concreto, tempo ou lugar ("São 22h, seu script puxa o lote de internações…").
- Atrito — o comportamento do sistema governamental que bloqueia (FTP que congela,
502sem aviso, CSV de 8 GB). - Virada — a resolução em uma frase, apontando para a ferramenta ("…exige um crawler com paciência de plantonista" →
datasus-fetcher).
Regras:
- Narrativa não é hype. Continuam proibidos "revolucionário", superlativos vazios e promessas sem mecanismo. A cena cria contexto; a prova continua sendo comando executável e número verificável.
- Toda afirmação factual da cena deve ser defensável — use os números que a própria página já documenta (29 GB descompactados do CNPJ, 19.607 séries do SGS, 594 estações do INMET em 2025) ou hedge ("costuma", "pode"). Sem depoimentos inventados, sem estatísticas sem fonte. Tamanhos e tempos vêm de medições versionadas em
benchmarks/; número que não tem JSON lá não entra na página. - Normas, referência de API e configuração ficam fora — texto normativo e contratual permanece seco e literal.
- Front-matter (
title/description) permanece factual para SEO/Open Graph, mesmo quando a abertura é narrativa.
Template para Pacotes de Dados (fetchers)¶
# <nome-do-pacote>: <descrição curta>
 
<2-3 frases: o que faz, qual fonte, para quem>
---
## Instalação
## Uso Rápido
## CLI ← apenas se o pacote instala um comando
## API Python ← apenas se expõe uma API programática
## Datasets / Fontes de Dados ← se aplicável
## Desenvolvimento
## Changelog ← link para o CHANGELOG.md do repo
## Licença
Template para Pacotes de Infraestrutura¶
# <nome-do-pacote>: <descrição curta>
 
<2-3 frases>
---
## Instalação
## Uso Rápido
## Módulos
## Princípios de Design
## Desenvolvimento
## Changelog ← link para o CHANGELOG.md do repo
## Licença
Seções Obrigatórias¶
## Instalação¶
Para pacotes publicados no PyPI (apenas quantilica-core e quantilica-cli):
## Instalação
\`\`\`bash
pip install <pacote>
\`\`\`
Com [uv](https://github.com/astral-sh/uv):
\`\`\`bash
uv add <pacote>
\`\`\`
Para pacotes distribuídos via índice próprio (todos os *-fetcher e *-sql, quantilica-analytics, quantilica-catalog):
## Instalação
\`\`\`bash
# Via CLI unificada (recomendado)
quantilica install <fonte>
# Ou como biblioteca no seu projeto
uv add <pacote> --index https://index.quantilica.com/simple/
\`\`\`
Para extras opcionais: pip install "<pacote>[extra]" (PyPI) ou uv add "<pacote>[extra]" --index https://index.quantilica.com/simple/ (índice próprio). Nunca use git+https em snippets públicos — o padrão foi abolido pelo ADR de distribuição (2026-07-30).
## Desenvolvimento¶
## Desenvolvimento
\`\`\`bash
git clone https://github.com/Quantilica/<pacote>.git
cd <pacote>
uv sync --dev
uv run pytest
\`\`\`
## Changelog¶
Todo pacote mantém um CHANGELOG.md (formato Keep a Changelog — ver Padronização de CHANGELOG.md); o README apenas aponta para ele:
## Changelog
Veja [CHANGELOG.md](CHANGELOG.md).
## Licença¶
## Licença
MIT — veja [LICENSE](LICENSE).
Pacotes em Conformidade¶
| Pacote | Tipo | Idioma | Badges |
|---|---|---|---|
bcb-sgs-fetcher |
Data Package | PT | ✓ |
bcb-sgs-sql |
Motor ETL | PT | ✓ |
comex-fetcher |
Data Package | PT | ✓ |
datasus-fetcher |
Data Package | PT | ✓ |
inmet-fetcher |
Data Package | PT | ✓ |
pdet-fetcher |
Data Package | PT | ✓ |
quantilica-catalog |
Infraestrutura | PT | ✓ |
quantilica-cli |
CLI | PT | ✓ |
quantilica-core |
Infraestrutura | PT | ✓ |
quantilica-analytics |
Infraestrutura | PT | ✓ |
rtn-fetcher |
Data Package | PT | ✓ |
ibge-sidra-fetcher |
Client Library | PT | ✓ |
sidra-pipelines |
Catálogo ETL | PT | ✓ |
sidra-sql |
Motor ETL | PT | ✓ |
tesouro-direto-fetcher |
Data Package | PT | ✓ |
Atualizado em: 2 de junho de 2026