Come faccio a generare la documentazione di Vim dalle note di Markdown o dai commenti incorporati o ci sono modi migliori per aggiungere documentazione?

Questa è una specie di due domande in una. Ultimamente ho trascorso molto tempo ad imparare a fondo vimscript, a imparare gli interni di Vim e a muovere i miei primi passi scrivendo plugin di Vim. Durante questo processo, ho tenuto ampie note nei singoli file di markdown e ho aggiunto molti commenti di "documentazione" in linea ai file vimscript.

Mi sento come se finalmente avessi del codice che vale la pena condividere e voglio iniziare ad aggiungere della documentazione effettiva . Non ho ancora creato nessuno dei miei file helpdoc, quindi sto ancora cercando di capire questo processo.

Senza alcuna esperienza o solida conoscenza di questo flusso di lavoro, ci sono due compiti che sto cercando di capire:

1. Generare file helpdoc dai miei file 'note' di markdown su vim / vimscript, così posso leggere / consultare rapidamente e facilmente da Vim in qualsiasi momento.
2. Analizzare la documentazione in linea dai miei file vimscript (simile al modo in cui shocco funziona per gli script di shell) per generare l'helpdoc associato per i vimscript.

Eventuali suggerimenti o consigli sulle idee ( questa è una cattiva idea perché ..., un'idea migliore è ... ), o come realizzarli sarebbe molto apprezzato.

Per quanto ne so, al momento non esiste una buona soluzione per entrambi i problemi, ma molte persone sarebbero interessate a risolverli.

Markdown è un superset di HTML, quindi direi che è improbabile che un approccio frontale alla conversione da markdown a Vim aiuti abbia successo. Se sai parlare Haskell, potresti provare a scrivere un backend di aiuto Vim per pandoc . Sarebbe un'ottima soluzione anche se non è perfetta.

Ci sono stati alcuni tentativi di farlo al contrario, convertire le pagine di aiuto di Vim in un formato utile. Ci sono alcuni script in giro che producono versioni HTML e PDF dell'aiuto ufficiale, con vari gradi di successo. Ma tutti fanno affidamento sul fatto che l'aiuto abbia uno stile più o meno omogeneo. Anche un lettore di aiuto Vim per qualcosa come il pandoc sarebbe un progetto utile.

Per quanto riguarda l'estrazione della documentazione dal codice Vim, esiste un parser per VimL in Python, JavaScript e VimL stesso, chiamato vimlparser . È abbastanza buono, non dovrebbe essere difficile scrivere qualcosa che analizza le fonti VimL e scarica commenti speciali. Essere in grado di convertire questi commenti in qualcosa come, diciamo, POD sarebbe anche molto utile.

html2vimdoc.py

Lo strumento più promettente che ho trovato è html2vimdoc.pyche può essere trovato qui http://peterodding.com/code/vim/tools e su github . Può convertire markdown e html nel formato di aiuto di vim. Le funzionalità pubblicizzate sono:

• Può gestire HTML complessi grazie a [BeautifulSoup] bs
• Genera automaticamente tag del file di aiuto di Vim per le intestazioni
• Genera sommario da titoli e tag
• Supporta strutture a blocchi nidificati come liste nidificate, blocchi preformattati all'interno di liste, ecc.
• Compatta ed espande gli elementi dell'elenco in base al numero medio di righe per elemento dell'elenco

Un'alternativa più vecchia è https://github.com/mklabs/vim-markdown-helpfile

C'è stata anche una discussione su /superuser//q/415470/generating-help-files-for-vim