Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

improve help doc HTML generation #17

Closed
justinmk opened this issue Jul 16, 2017 · 13 comments
Closed

improve help doc HTML generation #17

justinmk opened this issue Jul 16, 2017 · 13 comments

Comments

@justinmk
Copy link
Member

justinmk commented Jul 16, 2017

(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 justinmk changed the title help doc generation help doc HTML generation Jul 16, 2017
@justinmk justinmk changed the title help doc HTML generation improve help doc HTML generation Jul 16, 2017
@knight42

This comment has been minimized.

@gebulmer

This comment has been minimized.

@knight42
Copy link

knight42 commented Feb 7, 2018

@justinmk I have used h2h.py to generate the documentation hosting here, PTAL.

Does it need any modification?

@justinmk
Copy link
Member Author

justinmk commented Feb 7, 2018

@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.

@tweekmonster
Copy link

@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.

@justinmk
Copy link
Member Author

justinmk commented Feb 7, 2018

@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.

@tweekmonster
Copy link

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:

screen-shot-2018-02-07-19-50-50

screen-shot-2018-02-07-19-51-09

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.

@knight42
Copy link

knight42 commented Feb 8, 2018

@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
Copy link

@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.

@knight42
Copy link

@tweekmonster What's the status of your script? Could we use it now?

@tweekmonster
Copy link

@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.

@neovim neovim deleted a comment from knight42 Mar 26, 2019
@justinmk
Copy link
Member Author

@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)

@justinmk justinmk transferred this issue from neovim/bot-ci Sep 19, 2021
@justinmk
Copy link
Member Author

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

4 participants