Aula 19 - Automação de Documentação Técnica e SSGs 📚

📑 1. Fundamentos Teóricos & Análise Técnica

Em organizações complexas com dezenas de microsserviços e bibliotecas, a documentação centralizada desatualiza-se rapidamente se depender de wikis manuais desconectadas do repositório de código.

A abordagem Docs-as-Code com MkDocs Material unifica documentação e engenharia: 1. Arquitetura do MkDocs Material: - Gerador de sites estáticos rápido baseado em Python e Markdown, extensível via plugins e hooks em Python puro. - Fornece busca textual instantânea indexada localmente (Web Worker Search), suporte nativo a tags, cartões de navegação (Grid Cards), guias de código (Content Tabs) e anotações explicativas. 2. Ciclo Contínuo de Validação de Documentação: - Assim como o código de aplicação possui suítes de testes, a documentação deve passar por verificações de integridade: - Detecção de links quebrados internos e externos (Dead Link Checkers). - Verificação de formatação e linter de Markdown com markdownlint. - Verificação de cobertura de documentação de APIs públicas a partir de docstrings. 3. Deploy Automatizado e Isolamento: - Compilação dos arquivos .md em páginas HTML/CSS estáticas de altíssima velocidade e publicação autônoma no GitHub Pages via GitHub Actions ou deploys locais sob demanda.

📐 Arquitetura Conceitual & Diagrama de Fluxo

graph TD
    Repo["Arquivos Markdown (.md) em docs/"] --> Config["mkdocs.yml (Configuração Declarativa)"]
    Config --> Hook["Hooks em Python (Automação de Metadados / Validações)"]
    Hook --> Build["Compilação MkDocs: Geração de HTML/JS Estático"]
    Build --> LinkCheck["Validador de Links & Linter de Markdown"]
    LinkCheck --> Deploy["Deploy Seguro no GitHub Pages (gh-pages branch)"]
    style Repo fill:#e1f5fe,stroke:#01579b
    style Config fill:#fff3e0,stroke:#e65100
    style Hook fill:#f3e5f5,stroke:#7b1fa2
    style Build fill:#e8f5e9,stroke:#2e7d32
    style Deploy fill:#e0f2f1,stroke:#00695c

🔍 Pilares e Diretrizes Técnicas

Nesta unidade, aprofundamos os seguintes conceitos fundamentais: - Busca Instantânea em Client-Side: Indexação em Web Worker que permite localizar termos e símbolos instantaneamente sem chamadas a servidores externos. - Integração de Hooks em Python: Capacidade de injetar variáveis dinâmicas, gerar tabelas automatizadas e manipular a AST dos documentos durante o build. - Layout Totalmente Responsivo: Visualização perfeita em computadores, tablets e smartphones com navegação por abas e barra lateral recolhível. - Manutenibilidade ao Lado do Código: A documentação vive no mesmo repositório da funcionalidade, evoluindo conjuntamente no mesmo Pull Request.

🛠️ 2. Implementação Prática em Static Site Generators (SSGs), MkDocs Material e CI/CD

Abaixo está a implementação técnica de referência, estruturada com padrões de engenharia de software e foco em robustez:

// mkdocs_advanced_config.yml (Configuração Enterprise do MkDocs Material)
site_name: Portal de Engenharia de Software
theme:
  name: material
  language: pt-BR
  palette:
    # Alternância dinâmica entre tema claro e escuro
    - scheme: default
      primary: indigo
      accent: deep purple
      toggle:
        icon: material/brightness-7
        name: Mudar para Modo Escuro
    - scheme: slate
      primary: indigo
      accent: deep purple
      toggle:
        icon: material/brightness-4
        name: Mudar para Modo Claro
  features:
    - navigation.instant
    - navigation.tracking
    - navigation.tabs
    - navigation.sections
    - navigation.top
    - search.suggest
    - search.highlight
    - content.code.copy

markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed:
      alternate_style: true
  - admonition
  - attr_list

💡 Análise Passo a Passo do Código

1. Recurso navigation.instant: Transforma o portal em uma Single Page Application (SPA), eliminando o recarregamento total da página entre navegações.
2. Suporte a Mermaid via pymdownx.superfences: Renderiza blocos ```mermaid diretamente como gráficos vetoriais SVG.
3. Alternância de Paleta com Persistência: Memoriza a preferência do usuário por modo escuro ou claro no LocalStorage do navegador.

🎯 3. Próximos Passos & Sequência Didática