Pular para conteúdo

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-core e quantilica-cli são publicados no PyPI e usam pip install <pacote> / uv add <pacote>; os demais (ibge-sidra-fetcher, sidra-sql, bcb-sgs-sql, 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 (apenas quantilica-core e quantilica-cli) 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:

  1. Cena — segunda pessoa, artefato concreto, tempo ou lugar ("São 22h, seu script puxa o lote de internações…").
  2. Atrito — o comportamento do sistema governamental que bloqueia (FTP que congela, 502 sem aviso, CSV de 8 GB).
  3. 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>

![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 (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