DEV Community

Cover image for Gerando documentação vimdoc de plugins Neovim com Github Actions
Ellison Leão
Ellison Leão

Posted on

3

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>"
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Agora envie o novo worflow:

$ git add .github/workflows/docs.yml
$ git commit -m 'adicionando docs workflow'
$ git push
Enter fullscreen mode Exit fullscreen mode

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

Exemplo pode ser visto aqui

Links úteis

Se gostou do artigo, não esqueça de compartilhar em outras redes e aproveita e me segue também! https://linktr.ee/ellisonleao

Do your career a big favor. Join DEV. (The website you're on right now)

It takes one minute, it's free, and is worth it for your career.

Get started

Community matters

Top comments (1)

Collapse
 
dmass profile image
Douglas Massolari • Edited

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

A Workflow Copilot. Tailored to You.

Pieces.app image

Our desktop app, with its intelligent copilot, streamlines coding by generating snippets, extracting code from screenshots, and accelerating problem-solving.

Read the docs

👋 Kindness is contagious

Discover a treasure trove of wisdom within this insightful piece, highly respected in the nurturing DEV Community enviroment. Developers, whether novice or expert, are encouraged to participate and add to our shared knowledge basin.

A simple "thank you" can illuminate someone's day. Express your appreciation in the comments section!

On DEV, sharing ideas smoothens our journey and strengthens our community ties. Learn something useful? Offering a quick thanks to the author is deeply appreciated.

Okay