Skip to content

Reescrever o README para o usuário externo - #89

Open
maia-andre wants to merge 1 commit into
mainfrom
docs/readme-usuario-externo
Open

Reescrever o README para o usuário externo#89
maia-andre wants to merge 1 commit into
mainfrom
docs/readme-usuario-externo

Conversation

@maia-andre

Copy link
Copy Markdown
Collaborator

Resolve #22

O que muda com esse PR

O README passa a ser escrito para o usuário externo — quem instala o colibri para consultar os dados — e aponta para o site (https://gestaogovbr.github.io/colibri/) para tudo o mais. Conferi cada comando e exemplo contra o código da main e contra o lake de produção (somente leitura).

  • Instalação com ambiente virtual, em Mac/Linux e Windows (PowerShell, incluindo o contorno da política de execução); o passo do Homebrew para Mac (Atualizar README.md para usuários Mac #79) está preservado. URL do clone corrigida (heitorgama/colibrigestaogovbr/colibri).
  • Credenciais: o .segredos_template.yml ganha o perfil colibri-token-visualizador, que é o padrão dos comandos lake e não constava do template — sem ele o usuário externo não conseguia nem começar. O README explica os dois perfis e quando cada um é necessário. Não é preciso rodar colibri sincronizar: os comandos lake já baixam o catálogo sozinhos.
  • Consultar os dados vem primeiro (lake tables, query, download, years, ui), com a explicação pedida na issue: no SQL o caminho completo lake.<schema>.<tabela>, nos outros comandos só o nome — incluindo a mensagem de erro real do DuckDB, que já sugere o nome certo. Tabela dos três schemas e das views de main_marts que existem hoje (mrt_pncp_comprasgov_*, mrt_margem__ncms_*, mrt_tradutor_*); o README antigo citava mrt_pncp_comprasgov__resumo_anual e ncm_prefixos, que não existem mais.
  • colibri lake q (que não existe) → colibri lake query; exemplo de validação trocado por um que roda hoje (compras por ano de publicação). Link do painel "PNCP em Números" atualizado — o antigo em gov.br devolve 404.
  • Referência de pipeline/bucket sai do README: fica o essencial em "Para desenvolver" com links para os guias de instalação, desenvolvedor e analista do site. Arquitetura corrigida (colibri-devcolibri-prod, que é o padrão do código).
  • DuckDB UI: aviso sobre o caderno-exemplo que grava um trains.csv de 33 MB na pasta atual; trains.csv e /*.parquet (saída padrão de lake download na raiz) entram no .gitignore para não virarem commit acidental.

Como testar

Seguir o README do zero, com só o colibri-token-visualizador preenchido:

python3 -m venv env && source env/bin/activate
pip install -e .
cp .segredos_template.yml .segredos.yml     # preencher apenas o visualizador
colibri lake tables
colibri lake query "SELECT count(*) FROM lake.main_marts.mrt_pncp_comprasgov_compras"
colibri lake query "SELECT count(*) FROM mrt_pncp_comprasgov_compras"    # erro esperado, com a sugestão
colibri lake download mrt_pncp_comprasgov_compras && git status          # o .parquet não aparece como untracked

Links do README conferidos (todos respondem 200, inclusive a âncora do "S3 próprio" no site).

Checklist antes de mesclar na main

  • Formatar todos os arquivos yaml usando yamlfix .pre-commit run --all-files passa (yamlfix, ruff check, ruff format)
  • Executar testes unitários usando pytest — 38 passam
  • N/A ruff format (nenhum Python alterado)
  • N/A dbt test (nenhum modelo alterado)

O README passa a ser escrito para quem instala o colibri para consultar
os dados, e aponta para o site (gestaogovbr.github.io/colibri) para o
resto. Instalação com ambiente virtual em Mac/Linux e Windows
(PowerShell); URL do clone corrigida; os comandos `lake` vêm primeiro,
com a explicação do caminho completo no SQL (lake.<schema>.<tabela>)
contra o nome simples no download; `lake q` → `lake query`; tabelas
citadas passam a ser as que existem em produção; arquitetura com o
bucket padrão real (colibri-prod); referência de pipeline/bucket sai do
README e vira link para os guias do site.

O .segredos_template.yml ganha o perfil colibri-token-visualizador —
padrão dos comandos `lake`, que não constava do template. O .gitignore
passa a cobrir trains.csv (caderno-exemplo da DuckDB UI) e os .parquet
que `lake download` grava na raiz.

Resolve #22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Revisar README.md para que seja intuitivo para o usuário externo

1 participant