Как мне сгенерировать документацию Vim из заметок Markdown или встроенных комментариев, или есть лучшие способы добавить документацию?

Это своего рода два вопроса в одном. В последнее время я трачу много времени на глубокое изучение vimscript, изучение внутренних функций vim и выполнение моих первых шагов по написанию плагинов vim. Во время этого процесса я держал обширные заметки в отдельных файлах разметки и добавлял множество встроенных комментариев «документации» в файлы vimscript.

Я чувствую, что наконец-то получил код, которым стоит поделиться, и хочу начать добавлять некоторую актуальную документацию. Я еще не создал ни одного из моих собственных файлов справки, поэтому я все еще выясняю этот процесс.

Без какого-либо опыта или четкого понимания этого рабочего процесса я пытаюсь решить две задачи:

1. Создание файлов справки из файлов моих заметок 'примечания' в vim / vimscript, так что я могу быстро и легко читать / ссылаться из vim в любое время.
2. Анализ встроенной документации из моих файлов vimscript (аналогично тому, как shocco работает для сценариев оболочки) для генерации соответствующего справочного документа для vimscript.

Будем весьма благодарны за любые предложения или советы по поводу идей ( это плохая идея, потому что ..., лучшая идея ... ) или как их реализовать.

Насколько я знаю, в настоящее время нет хорошего решения для любой проблемы, но многие люди были бы заинтересованы в их решении.

Markdown - это расширенный набор HTML, поэтому я бы сказал, что маловероятно, что фронтальный подход к конвертации из markdown в Vim поможет. Если вы можете говорить на Хаскеле, вы можете попробовать написать бэкэнд Vim для pandoc . Это было бы очень хорошим решением, даже если оно не идеально.

Было несколько попыток сделать это наоборот, конвертировать справочные страницы Vim в какой-нибудь полезный формат. Есть несколько скриптов, которые генерируют HTML и PDF версии официальной справки с разной степенью успеха. Но все они полагаются на помощь, более или менее однородную по стилю. Даже читатель помощи Vim для чего-то вроде pandoc был бы стоящим проектом.

Что касается извлечения документации из кода Vim, то есть анализатор для VimL на Python, JavaScript и самого VimL с именем vimlparser . Это довольно хорошо, нетрудно написать что-то, что анализирует исходники VimL и выдает специальные специально созданные комментарии. Возможность конвертировать эти комментарии в что-то вроде, скажем, POD также было бы очень полезно.

html2vimdoc.py

Самый многообещающий инструмент, который я нашел, находится html2vimdoc.pyздесь http://peterodding.com/code/vim/tools и на github . Он может конвертировать markdown и html в формат справки vim. Рекламируемые функции:

• Он может работать со сложным HTML благодаря [BeautifulSoup] bs
• Автоматически генерирует теги файла справки Vim для заголовков
• Создает оглавление из заголовков и тегов
• Поддерживает структуры вложенных блоков, такие как вложенные списки, предварительно отформатированные блоки внутри списков и т. Д.
• Сжатие и расширение элементов списка на основе среднего числа строк на элемент списка

Более старая альтернатива - https://github.com/mklabs/vim-markdown-helpfile

Также было обсуждение на /superuser//q/415470/generating-help-files-for-vim