Automatizando documentação em PHP com Autodocs

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

1. Continuous Documentation Criando documentação de forma automatizada em PHP com Minicli, Autodocs e GitHub Actions
2. 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
3. Desafios e oportunidades de um novo produto Como tudo começou
4. Como tudo começou: Chainguard Academy
5. Como tudo começou: Chainguard Academy
6. Academy Hoje
8. Como escalamos a documentação de 400+ imagens de contêiner usando PHP e GitHub Actions Autodocs
9. • 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
11. • 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
13. • 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"
16. Criando um framework reusável para Automação de documentos markdown Open Sourcing Autodocs
17. 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
18. 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
19. Demo Time! https://github.com/erikaheidi/autodocs-demo
20. Obrigada =) https://twitter.com/erikaheidi https://github.com/erikaheidi/autodocs https://edu.chainguard.dev