Gerando documentação vimdoc de plugins Neovim com Github Actions
Tags: neovim, plugin, githubactions, pandoc
Published: 2023-07-26 20:40:59

_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](https://vimdoc.sourceforge.net/htmldoc/helphelp.html#help-writing)
  - 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:

```yaml
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:

```bash
$ 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:

```bash
$ 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


![resultado do job](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/5pre86sg64pzp5y69bdg.png)

Exemplo pode ser visto [aqui](https://github.com/ellisonleao/carbon-now.nvim/actions/runs/5673377787)


## Links úteis

- Documentação da [github action](https://kdheepak.com/panvimdoc/)
- Exemplo de um bom [README](https://github.com/folke/lazy.nvim/blob/main/README.md) vs o [resultado](https://github.com/folke/lazy.nvim/blob/main/doc/lazy.nvim.txt) 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