Comment générer la documentation Vim à partir de notes Markdown ou de commentaires en ligne, ou existe-t-il de meilleures façons d'ajouter de la documentation?

C'est en quelque sorte deux questions en une. Dernièrement, j'ai passé beaucoup de temps à apprendre Vimscript en profondeur, à apprendre les composants internes de Vim et à faire mes premiers pas pour écrire des plugins Vim. Au cours de ce processus, j'ai gardé de nombreuses notes dans des fichiers de démarque individuels et ajouté de nombreux commentaires de «documentation» en ligne aux fichiers vimscript.

J'ai l'impression d'avoir enfin du code qui mérite d'être partagé et je veux commencer à ajouter de la documentation réelle . Je n'ai pas encore créé mes propres fichiers d'aide, donc je suis toujours en train de comprendre ce processus.

Sans aucune expérience ou compréhension solide de ce flux de travail, j'essaie de comprendre deux tâches:

1. Générer des fichiers helpdoc à partir de mes fichiers de notes de démarque sur vim / vimscript, afin que je puisse lire / référencer rapidement et facilement à partir de vim à tout moment.
2. Analyser la documentation en ligne de mes fichiers vimscript (similaire à la façon dont shocco fonctionne pour les scripts shell) pour générer le helpdoc associé pour les vimscripts.

Toutes suggestions ou conseils sur les idées ( c'est une mauvaise idée parce que ..., une meilleure idée est ... ), ou comment les réaliser seraient grandement appréciés.

Pour autant que je sache, il n'y a actuellement aucune bonne solution pour l'un ou l'autre problème, mais beaucoup de gens seraient intéressés à les résoudre.

Markdown est un sur-ensemble de HTML, donc je dirais qu'une approche frontale de la conversion du markdown en aide Vim a peu de chances de réussir. Si vous parlez Haskell, vous pouvez essayer d'écrire un backend d'aide Vim pour pandoc . Ce serait une très bonne solution même si elle n'est pas parfaite.

Il y a eu quelques tentatives pour le faire dans l'autre sens, convertir les pages d'aide de Vim en un format utile. Il existe quelques scripts flottants qui produisent des versions HTML et PDF de l'aide officielle, avec plus ou moins de succès. Mais ils comptent tous sur une aide de style plus ou moins homogène. Même un lecteur d'aide Vim pour quelque chose comme pandoc serait un projet valable.

En ce qui concerne l'extraction de la documentation à partir du code Vim, il existe un analyseur pour VimL en Python, JavaScript et VimL lui-même, nommé vimlparser . C'est assez bien, il ne devrait pas être difficile d'écrire quelque chose qui analyse les sources VimL et vide les commentaires spécialement conçus. Pouvoir convertir ces commentaires en quelque chose comme, disons, POD serait également très utile.

html2vimdoc.py

L'outil le plus prometteur que j'ai trouvé est celui html2vimdoc.pyqui peut être trouvé ici http://peterodding.com/code/vim/tools et sur github . Il peut convertir le markdown et le html au format d'aide de vim. Les fonctionnalités annoncées sont:

• Il peut gérer du HTML complexe grâce à [BeautifulSoup] bs
• Génère automatiquement des balises de fichier d'aide Vim pour les en-têtes
• Génère une table des matières à partir des en-têtes et des balises
• Prend en charge les structures de blocs imbriquées comme les listes imbriquées, les blocs préformatés à l'intérieur des listes, etc.
• Compacte et étend les éléments de liste en fonction du nombre moyen de lignes par élément de liste

Une alternative plus ancienne est https://github.com/mklabs/vim-markdown-helpfile

Il y a également eu une discussion sur /superuser//q/415470/generating-help-files-for-vim