Upgrade to PRO for Only $50/Year—Limited-Time Offer! 🔥

Automatizando documentação em PHP com Autodocs

Automatizando documentação em PHP com Autodocs

Slides da apresentação feita para a Weekly PHP da PicPay em 05/02/24.

Erika Heidi

February 05, 2024
Tweet

More Decks by Erika Heidi

Other Decks in Programming

Transcript

  1. Sobre a Érika • Staff Developer Experience Engineer na Chainguard

    • Background em PHP e Linux, mas hoje trabalhando com documentação e um pouco de devRel • Autora do Minicli e outros projetinhos PHP open source • Sempre procurando um jeito de automatizar o que puder
  2. • Motivação ◦ Oferecer páginas com informações básicas para cada

    imagem ◦ Acompanhar o ritmo intenso em que novas imagens eram publicadas • Oportunidade ◦ Arquivos YAML ricos em metadados descrevendo a configuração de cada imagem • Objetivos iniciais para cada imagem ◦ "Landing page" similar ao que vemos no Docker Hub ◦ Página com informações sobre proveniência, SBOMs e assinaturas Autodocs para Chainguard Images Actions Workflow, versão 1 1. Fazer checkout do repositório contendo source das imagens em um diretório de trabalho 2. Fazer checkout do repositório onde a documentação será publicada para o mesmo diretório de trabalho 3. Executar o Autodocs usando como "data source" os arquivos YAML das imagens 4. Copiar conteúdo markdown gerado para o diretório correto dentro do site de docs 5. Abrir um Pull Request para o site de docs, contendo o "diff" gerado pelos arquivos novos / modificados Protótipo
  3. • Novas Páginas ◦ Detalhes da Imagem / Variantes •

    Changelog ◦ Um simples changelog para saber quais novas imagens foram adicionadas • Notificação no Slack ◦ Facilitando review ao compartilhar link direto para o PR ◦ Envia mensagem para um canal dedicado apenas quando um novo PR Autodocs é aberto Autodocs para Chainguard Images Workflow V2 Upgrades 1. Check out Images repository to working directory 2. Check out Academy repository to working directory 3. Copy current changelog.md and last-update.md into working directory 4. Run autodocs using the Images repository as data source 5. Copy generated markdown files from the working directory to the correct location at Academy 6. Save changelog and last-update.md files with updated information 7. Create a Pull Request to the Academy repository with the diff caused by content being added, using the body of the last-update.md file as content 8. Send a notification to Slack with the same content as the body of the PR
  4. • Imagens demais para um site estático? ◦ Problemas com

    navegação e loading time • Configuração de imagens começou a fragmentar ◦ APIs experimentais descontinuadas ◦ Configs movidas para CI/CD com Terraform • Projeto precisou ser refatorado algumas vezes devido às mudanças constantes Autodocs para Chainguard Images "Growing Pains"
  5. Open Sourcing Autodocs • Como facilitar reuso dessa estrutura para

    outros projetos? • Nasce erikaheidi/autodocs, um pequeno framework de automação para documentos markdown • Combinada a uma aplicação Minicli para "buildar" docs baseados em templates • Data sources abstraídas em arquivos JSON
  6. Criando uma aplicação Autodocs 1. Criar uma aplicação Minicli 2.

    Adicionar erikaheidi/autodocs como dependência 3. Configurar Autodocs e definir onde fazer output, onde buscar por JSONs, templates, etc 4. Registrar o serviço Autodocs 5. Criar um comando para fazer build dos arquivos markdown 6. Criar uma ou mais classes para representar cada página da documentação. Opcionalmente, usar JSON feeds e templates 7. Rodar o comando de build e ver o resultado =) TL;DR para esse tutorial