Dificuldade: intermediário
Escrever documentação nem sempre é uma das tarefas mais prazerosas, mas ter uma boa documentação nos nossos projetos é o que realmente faz diferença. Ainda mais quando usamos ferramentas que nos auxiliam nessa escrita.
Nesse post vamos ensinar como automatizar a geração da documentação específica para plugins Neovim utilizando Github Actions
Entendendo o fluxo
Assumindo que entendemos o fluxo básico das Github Actions, temos o seguinte fluxo para a geração da doc:
- Fazemos um push na branch principal (geralmente chamada de
main
) - Um job chamado
docs
é iniciado com os seguintes passos:- Conversão do
README.md
do seu projeto em um arquivo .txt no formato vimdoc - Criamos um commit e fazemos o push na mesma branch com o resultado da conversão
- Conversão do
Convertendo isso para o Github Actions, temos:
- Crie um arquivo
.github/workflows/docs.yml
com o seguinte conteúdo:
on:
push:
branches:
- main # aqui nossa branch principal se chama `main`
jobs:
docs:
runs-on: ubuntu-latest
needs: test
steps:
- uses: actions/checkout@v3
- name: panvimdoc
uses: kdheepak/panvimdoc@main
with:
vimdoc: nome-do-seu-projeto # sem extensão .txt
version: "Neovim >= 0.8.0"
demojify: true # coloque false caso queira manter os emojis
treesitter: true
- name: Push changes
uses: stefanzweifel/git-auto-commit-action@v4
with:
commit_message: "auto-generate vimdoc"
commit_user_name: "github-actions[bot]"
commit_user_email: "github-actions[bot]@users.noreply.github.com"
commit_author: "github-actions[bot] <github-actions[bot]@users.noreply.github.com>"
Preparando seu README
Para um bom resultado de uma documentação vimdoc, recomendamos que seu README tenha pelo menos:
- Uma seção
Sobre
- Uma seção
Instalação
- Uma seção
Como usar
O uso de tabelas, bullet points também é suportado e recomendado. Quanto mais detalhes conseguir colocar na documentação, melhor ficará o resultado (até emojis são suportados!)
Colocando tudo para funcionar
Antes de commitar e rodar a action pela primeira vez, crie o arquivo vazio da doc:
$ touch doc/nome-do-seu-projeto.txt
$ git add doc/nome-do-seu-projeto.txt
$ git commit -m 'adicionando arquivo vimdoc'
$ git push
Agora envie o novo worflow:
$ git add .github/workflows/docs.yml
$ git commit -m 'adicionando docs workflow'
$ git push
Se tudo deu certo, você já poderá ver o resultado do workflow com seu vimdoc gerado na branch principal. Exemplo do resultado na imagem abaixo
Exemplo pode ser visto aqui
Links úteis
- Documentação da github action
- Exemplo de um bom README vs o resultado em vimdoc
Se gostou do artigo, não esqueça de compartilhar em outras redes e aproveita e me segue também! https://linktr.ee/ellisonleao
Top comments (1)
Muito bom, @ellisonleao !
Com certeza vou usar no meu plugin!