Gerando documentação vimdoc de plugins Neovim com Github Actions

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:

1. Fazemos um push na branch principal (geralmente chamada de main)
2. 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

Convertendo isso para o Github Actions, temos:

1. 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

Comments

[Douglas Massolari]

Muito bom, @ellisonleao !
Com certeza vou usar no meu plugin!