Jak wygenerować dokumentację Vima z notatek Markdown lub wbudowanych komentarzy, czy są lepsze sposoby dodawania dokumentacji?

Jest to rodzaj dwa pytania w jednym. Ostatnio dużo czasu poświęcam na dogłębne uczenie się vimscript, uczenie się wewnętrznych elementów vima i stawianie pierwszych kroków w pisaniu wtyczek vim. W trakcie tego procesu trzymałem obszerne notatki w poszczególnych plikach przecen i dodawałem wiele wbudowanych komentarzy dotyczących dokumentacji do plików vimscript.

Wydaje mi się, że w końcu mam jakiś kod, który warto udostępnić i chcę zacząć dodawać faktyczną dokumentację. Nie stworzyłem jeszcze żadnych własnych plików helpdoc, więc wciąż zastanawiam się nad tym procesem.

Bez żadnego doświadczenia ani dogłębnego zrozumienia tego przepływu pracy próbuję wymyślić dwa zadania:

1. Generowanie plików helpdoc z moich plików notatek na vim / vimscript, dzięki czemu mogę szybko i łatwo czytać / odwoływać się z vima w dowolnym momencie.
2. Przetwarzanie wbudowanej dokumentacji z moich plików vimscript (podobnie jak działa shocco dla skryptów powłoki) w celu wygenerowania powiązanego helpdoc dla skryptów vimscript.

Wszelkie sugestie lub porady dotyczące pomysłów ( jest to zły pomysł, ponieważ ... lepszym pomysłem jest ... ) lub jak je zrealizować byłyby bardzo mile widziane.

O ile mi wiadomo, obecnie nie ma dobrego rozwiązania żadnego z tych problemów, ale wiele osób byłoby zainteresowanych ich rozwiązaniem.

Markdown jest nadzbiorem HTML, więc powiedziałbym, że frontalne podejście do konwersji z Markdown na pomoc Vima jest mało prawdopodobne. Jeśli potrafisz mówić w języku Haskell, możesz spróbować napisać backend pomocy Vima dla pandoc . To byłoby bardzo miłe rozwiązanie, nawet jeśli nie jest idealne.

Było kilka prób zrobienia tego na odwrót, przekonwertowania stron pomocy Vima na jakiś użyteczny format. Istnieje kilka skryptów, które pływają wokół, tworząc wersje HTML i PDF oficjalnej pomocy, z różnym powodzeniem. Ale wszystkie polegają na tym, że pomoc jest mniej więcej jednorodna w stylu. Nawet pomocnik Vima dla czegoś takiego jak pandoc byłby wartościowym projektem.

Jeśli chodzi o wyodrębnianie dokumentacji z kodu Vima, istnieje parser dla VimL w Pythonie, JavaScript i samej VimL, ​​o nazwie vimlparser . Jest całkiem niezły, nie powinno być trudno napisać coś, co przeanalizuje źródła VimL i zrzuci specjalnie spreparowane komentarze. Bardzo przydatne byłoby również przekonwertowanie tych komentarzy na coś takiego, powiedzmy, POD .

html2vimdoc.py

Najbardziej obiecującym narzędziem, które znalazłem, jest to, html2vimdoc.pyktóre można znaleźć tutaj http://peterodding.com/code/vim/tools i na github . Może konwertować markdown i html do formatu pomocy vima. Reklamowane funkcje to:

• Potrafi radzić sobie ze złożonym HTML dzięki bs [BeautifulSoup]
• Automatycznie generuje znaczniki pliku pomocy Vima dla nagłówków
• Generuje spis treści z nagłówków i tagów
• Obsługuje zagnieżdżone struktury bloków, takie jak zagnieżdżone listy, wstępnie sformatowane bloki wewnątrz list itp.
• Kompaktuje i rozwija elementy listy na podstawie średniej liczby wierszy na element listy

Starszą alternatywą jest https://github.com/mklabs/vim-markdown-helpfile

Odbyła się również dyskusja na /superuser//q/415470/generating-help-files-for-vim