# Arquitetura da documentação

## Stack escolhida

O site usa `Sphinx` com `MyST`, `autodoc` e `Furo`.

Motivos:

- Markdown continua como fonte principal.
- `autodoc` puxa a referência da API direto dos docstrings.
- `MyST` mantém o conteúdo do site em Markdown com recursos Sphinx.
- `Furo` entrega um layout limpo, responsivo e fácil de navegar.
- `sphinx-copybutton` adiciona o botão de copiar nos blocos de código.
- `sphinx.ext.githubpages` prepara o artefato para GitHub Pages.

## Mapa do site

- Início
- Arquitetura
- Começando
- Guias
  - Configuração de certificado
  - Primeira emissão
  - Consulta
  - Cancelamento
  - Substituição
  - DANFSe PDF
  - IBSCBS
- Referência da API
  - Cliente
  - Modelos
  - XML Builder
  - XML Signer
  - PDF Generator
  - Exceções
  - Utilitários
- Apêndice
  - Troubleshooting
  - Matriz de ambiente
  - Release e versionamento

## Layout da home

A home do site deve manter:

- hero curto;
- snippet de instalação;
- quickstart funcional e enxuto;
- CTA visível para guias e referência da API;
- link explícito para o README do repositório.

## O que fica no README

O README continua sendo a face do pacote no PyPI e no GitHub.

Fica no README:

- instalação;
- quickstart mínimo;
- exemplos principais;
- link para a documentação completa.

Os metadados do pacote apontam para o site da documentação como `Homepage`
e mantêm o repositório separado como `Repository`.

Sai do README:

- referência exaustiva de API;
- guias longos;
- detalhes de publicação;
- material de apêndice.

## Regras de renderização

- Blocos de código com syntax highlight e botão de copiar.
- Páginas legíveis sem depender de JavaScript para conteúdo principal.
- Navegação lateral em seções aninhadas.
- Busca global habilitada.
- Site responsivo com sidebar colapsável no mobile.
- API pages renderizadas por docstrings no código-fonte.

## Publicação

O site será publicado como conteúdo estático via GitHub Pages.

Fluxo previsto:

1. `uv sync --extra dev --group docs`
2. `uv run sphinx-build -b html docs site`
3. upload do artefato do site no GitHub Actions
4. deploy para Pages a partir do artefato gerado

O ponto de entrada do site fica em `https://roberto-mello.github.io/pynfse-nacional/`.