¿Cómo genero documentación de Vim a partir de notas de Markdown o comentarios en línea, o hay mejores formas de agregar documentación?

Esta es una especie de dos preguntas en una. Últimamente he pasado mucho tiempo aprendiendo vimscript en profundidad, aprendiendo lo interno de vim y dando mis primeros pasos escribiendo plugins vim. Durante este proceso, he mantenido notas extensas en archivos de rebajas individuales y agregué muchos comentarios en línea de 'documentación' a los archivos vimscript.

Siento que finalmente tengo un código que vale la pena compartir, y quiero comenzar a agregar documentación real . Todavía no he creado ninguno de mis propios archivos de helpdoc, por lo que todavía estoy descubriendo ese proceso.

Sin ninguna experiencia aún o comprensión sólida de este flujo de trabajo, hay dos tareas que estoy tratando de resolver:

1. Generando archivos helpdoc a partir de mis archivos de 'notas' de Markdown en vim / vimscript, para que pueda leer / hacer referencia rápida y fácilmente desde vim en cualquier momento.
2. Analizar la documentación en línea de mis archivos vimscript (similar a la forma en que shocco funciona para los scripts de shell) para generar el helpdoc asociado para los vimscripts.

Cualquier sugerencia o consejo sobre las ideas ( esta es una mala idea porque ..., una mejor idea es ... ), o cómo lograrlas sería muy apreciada.

Hasta donde sé, actualmente no hay una buena solución para ninguno de los problemas, pero mucha gente estaría interesada en resolverlos.

Markdown es un superconjunto de HTML, por lo que diría que un enfoque frontal para la conversión de Markdown a Vim es poco probable. Si puede hablar Haskell, puede intentar escribir un backend de ayuda de Vim para pandoc . Esa sería una solución muy buena, incluso si no es perfecta.

Ha habido algunos intentos de hacerlo al revés, convertir las páginas de ayuda de Vim a algún formato útil. Hay algunos scripts flotando que producen versiones HTML y PDF de la ayuda oficial, con diversos grados de éxito. Pero todos confían en que la ayuda tenga un estilo más o menos homogéneo. Incluso un lector de ayuda de Vim para algo como Pandoc sería un proyecto que valga la pena.

En cuanto a la extracción de documentación del código de Vim, hay un analizador para VimL en Python, JavaScript y VimL, ​​llamado vimlparser . Es bastante bueno, no debería ser difícil escribir algo que analice las fuentes de VimL y arroje comentarios especiales diseñados. Ser capaz de convertir estos comentarios en algo como, por ejemplo, POD también sería muy útil.

html2vimdoc.py

La herramienta más prometedora que he encontrado es la html2vimdoc.pyque se puede encontrar aquí http://peterodding.com/code/vim/tools y en github . Puede convertir markdown y html al formato de ayuda de vim. Las características anunciadas son:

• Puede manejar HTML complejo gracias a [BeautifulSoup] bs
• Genera automáticamente etiquetas de archivo de ayuda de Vim para encabezados
• Genera tabla de contenido a partir de encabezados y etiquetas
• Admite estructuras de bloques anidados como listas anidadas, bloques preformateados dentro de listas, etc.
• Compacta y expande los elementos de la lista en función del número promedio de líneas por elemento de la lista

Una alternativa anterior es https://github.com/mklabs/vim-markdown-helpfile

También ha habido una discusión en /superuser//q/415470/generating-help-files-for-vim