Como faço para gerar documentação do Vim a partir de anotações do Markdown ou comentários embutidos, ou existem maneiras melhores de adicionar documentação?

Esse é o tipo de duas perguntas em uma. Ultimamente, tenho gasto muito tempo aprendendo o vimscript em profundidade, aprendendo os aspectos internos do vim e dando os primeiros passos para escrever plugins do vim. Durante esse processo, eu tenho mantido anotações extensas em arquivos de remarcação individuais e adicionado muitos comentários embutidos de 'documentação' aos arquivos vimscript.

Sinto que finalmente recebi algum código que vale a pena compartilhar e quero começar a adicionar alguma documentação real . Ainda não criei nenhum dos meus arquivos de helpdoc, então ainda estou descobrindo esse processo.

Sem nenhuma experiência ainda ou sólido entendimento desse fluxo de trabalho, estou tentando descobrir duas tarefas:

1. Gerando arquivos helpdoc a partir dos meus arquivos de anotações no vim / vimscript, para que eu possa ler / fazer referência rápida e facilmente do vim a qualquer momento.
2. Analisando a documentação embutida dos meus arquivos vimscript (semelhante à maneira como o shocco trabalha para shell scripts) para gerar o helpdoc associado para os vimscripts.

Todas as sugestões ou conselhos sobre as idéias ( essa é uma péssima idéia porque ..., uma idéia melhor é ... ) ou como realizá-las serão muito apreciadas.

Até onde eu sei, atualmente não existe uma boa solução para nenhum dos problemas, mas muitas pessoas estariam interessadas em resolvê-los.

O markdown é um superconjunto do HTML, então eu diria que uma abordagem frontal da conversão da ajuda do markdown para o Vim provavelmente não será bem-sucedida. Se você pode falar Haskell, tente escrever um back-end de ajuda do Vim para o pandoc . Essa seria uma solução muito boa, mesmo que não seja perfeita.

Houve algumas tentativas de fazer o contrário, converter as páginas de ajuda do Vim para algum formato útil. Existem alguns scripts que produzem versões em HTML e PDF da ajuda oficial, com graus variados de sucesso. Mas todos confiam na ajuda de ser mais ou menos homogênea em estilo. Mesmo um leitor de ajuda do Vim para algo como pandoc seria um projeto que vale a pena.

Quanto à extração de documentação do código Vim, há um analisador para VimL no Python, JavaScript e no próprio VimL, ​​chamado vimlparser . É muito bom, não deve ser difícil escrever algo que analise fontes do VimL e despeje comentários especiais criados. Ser capaz de converter esses comentários em algo como, por exemplo, POD também seria muito útil.

html2vimdoc.py

A ferramenta mais promissora que encontrei é a html2vimdoc.pyque pode ser encontrada aqui http://peterodding.com/code/vim/tools e no github . Ele pode converter markdown e html no formato de ajuda do vim. Os recursos anunciados são:

• Ele pode lidar com HTML complexo graças a [BeautifulSoup] bs
• Gera automaticamente tags de arquivo de ajuda do Vim para títulos
• Gera sumário a partir de cabeçalhos e tags
• Oferece suporte a estruturas de blocos aninhados, como listas aninhadas, blocos pré-formatados dentro de listas, etc.
• Compacta e expande itens de lista com base no número médio de linhas por item de lista

Uma alternativa mais antiga é https://github.com/mklabs/vim-markdown-helpfile

Também houve uma discussão em /superuser//q/415470/generating-help-files-for-vim