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: Pacotes publicados no PyPI (quantilica-core, quantilica-cli, sidra-fetcher, sidra-sql, datasus-fetcher, bcb-sgs-fetcher, bcb-sgs-sql) usam pip install <pacote> / uv add <pacote>; os demais (fetchers restantes, analytics, catalog) são instalados via quantilica 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:

![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square) ![Python](https://img.shields.io/badge/python-3.12+-blue.svg?style=flat-square)

A versão Python deve corresponder ao requires-python do pyproject.toml.
Licença MIT para todos os pacotes.
Badge de CI apenas em pacotes com workflow de testes ativo.
Pacotes publicados no PyPI adicionam um badge de versão do PyPI: ![PyPI](https://img.shields.io/pypi/v/<pacote>.svg?style=flat-square).

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, 502 sem 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 (245 GB, 17.000 séries, 39 GB) ou hedge ("costuma", "pode"). Sem depoimentos inventados, sem estatísticas sem fonte.
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>

![License: MIT](...) ![Python](...)

<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>

![License: MIT](...) ![Python](...)

<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 (quantilica-core, quantilica-cli, sidra-fetcher, sidra-sql, datasus-fetcher, bcb-sgs-fetcher, bcb-sgs-sql):

## 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 (fetchers, 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	✓
`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