improve help doc HTML generation
justinmk opened this issue · 13 comments
(migrated from neovim/bot-ci#12)
Use h2h.py python script to generate help doc HTML instead of the old awk script.
@tweekmonster also did work on an improved vimdoc-to-HTML generator, might want to use that instead.
@justinmk Perhaps I have missed something, but I couldn't find any old awk script in this project. Is this issue outdated?
@knight42 AFAICT this issue is referring to the awk script in runtime/doc/makehtml.awk
@knight42 Looks good. Next steps would be to apply the colors (not layout) from the old one: https://neovim.io/doc/user/
Then modify the bot-ci script so that it runs h2h.py . That means we need to install https://github.com/c4rlo/vimhelp during a CI step, or just copy-paste the relevant parts of it into this repo.
The old styling uses hacks like this, hopefully we can do something nicer (CSS) with h2h.py.
@justinmk I am able to generate better (IMO) html docs, but the script isn't as simple as h2h.py. I'll work on cleaning it up and generating a set sometime in the next week to get opinions.
@tweekmonster Awesome! It's ok if the script isn't simple, since this will be running in bot-ci we can do crazy things. Looking forward to your layout improvements.
Got my ancient script sorted out enough to generate some HTML: https://vimdoc.dev.esdf.io/ (Home server, so might be offline occasionally)
It still needs to be cleaned up a little and documented. It's also missing the global-hamburger-menu-nav that I was last working on.
Some links have a hover tooltip that's currently isn't interactive. They're automatic links (as in, not tags) that are approximate matches for what might otherwise be hard to find:
Almost all lines are anchored as well. Making it possible to link to a specific line, not just tags: https://vimdoc.dev.esdf.io/motion.html#L336
I'm planning to add some very light scripting to make them interactive.
@justinmk Perhaps we should generate the documentation using @tweekmonster 's script instead of h2h.py? I think the former one generates prettier docs as well.
@tweekmonster The docs may look better if we get rid of the vim modelines in each file?
@tweekmonster The docs may look better if we get rid of the vim modelines in each file?
I'll defer such decisions to Justin. My opinion is that they're at the very bottom of each file and can't really detract from the overall aesthetic.
My actual goal for generating these is to create online and searchable docs that could be compared with past versions. I wanted to keep the original text (minus concealed chars) intact.
@tweekmonster What's the status of your script? Could we use it now?
@knight42 Really sorry for not replying sooner. I got caught up in some personal stuff + work related pressure. I'm going to try and get this dealt with this week. If it looks like I'm going to get swept up again, I'll just post the script somewhere and let someone else sort it out.
@tweekmonster Any chance you could post that script? Don't worry about cleaning it up. Even just the improved regexes/patterns would save me some time. I'm currently hacking on this (adapted from the above-mentioned h2h.py, which turns out to be quite lacking)
Use h2h.py python script to generate help doc HTML instead of the old awk script.