Як створити документацію Vim із приміток Markdown або вбудованих коментарів, або є кращі способи додати документацію?

Це свого роду два питання в одному. Останнім часом я витрачав багато часу на вивчення поглибленого vimscript, вивчення внутрішнього вигляду Vim та здійснення перших кроків щодо написання плагінів vim. Під час цього процесу я веду обширні записки в окремих файлах розмітки та додаю до файлів vimscript безліч вбудованих коментарів до документації.

Я відчуваю, що нарешті отримав якийсь код, який варто поділитися, і хочу почати додавати фактичну документацію. Я ще не створив жодного з моїх власних файлів довідки, тому я все ще з’ясовую цей процес.

Не маючи жодного досвіду чи міцного розуміння цього робочого процесу, я намагаюся вирішити два завдання:

1. Генерування файлів довідки з моїх розміток файлів «приміток» на vim / vimscript, тому я можу в будь-який час читати / посилатись швидко та легко з vim.
2. Аналіз вбудованої документації з моїх файлів vimscript (подібно до того, як shocco працює для оболонок скриптів) для створення пов'язаного довідкового документа для vimscripts.

Будемо дуже вдячні за будь-які пропозиції чи поради щодо цих ідей ( це погана ідея, тому що ..., краща ідея ... ), або як їх здійснити.

Наскільки я знаю, наразі немає жодного хорошого рішення для будь-якої проблеми, але багато людей були б зацікавлені у їх вирішенні.

Markdown - це набір HTML, тому я б сказав, що фронтальний підхід до переходу від розмітки до допомоги Vim навряд чи вдасться. Якщо ви можете говорити Haskell, ви можете спробувати написати допоміжний сервіс Vim для pandoc . Це було б дуже приємне рішення, навіть якщо воно не ідеальне.

Було кілька спроб зробити це навпаки, перетворити довідкові сторінки Vim у якийсь корисний формат. Існує кілька сценаріїв, які створюють HTML та PDF версії офіційної довідки з різним ступенем успіху. Але всі вони покладаються на те, що допомога є більш-менш однорідною за стилем. Навіть читач допомоги Vim для чогось на зразок pandoc був би гідним проектом.

Що стосується вилучення документації з коду Vim, то існує аналізатор VimL в Python, JavaScript та сам VimL під назвою vimlparser . Це досить добре, не повинно бути важко написати щось, що розбирає джерела VimL і скидає спеціальні майстерні коментарі. Бути в змозі перетворити ці коментарі на щось на зразок, скажімо, ПОД також було б дуже корисно.

html2vimdoc.py

Найперспективніший інструмент, який я знайшов, це той, html2vimdoc.pyякий можна знайти тут http://peterodding.com/code/vim/tools та на github . Він може конвертувати розмітку та HTML у формат довідки vim. Рекламовані функції:

• Він може мати справу зі складним HTML завдяки Bs [BeautifulSoup]
• Автоматично генерує теги файлів довідки Vim для заголовків
• Створює вміст із заголовків та тегів
• Підтримує вкладені структури блоків, такі як вкладені списки, попередньо відформатовані блоки всередині списків тощо.
• Ущільнює та розширює елементи списку на основі середньої кількості рядків на позицію списку

Старіша альтернатива - https://github.com/mklabs/vim-markdown-helpfile

Також було обговорено на /superuser//q/415470/generating-help-files-for-vim