-
Notifications
You must be signed in to change notification settings - Fork 712
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
Add a contrib/gendocs.py script for generating documentation web site #4997
base: master
Are you sure you want to change the base?
Conversation
11bd96f
to
1108634
Compare
Hey, this is great, I am just a bit concerned about the use of scala, I would have preferred a language that almost always available on posix platforms (such as sh/perl/python), but this is contrib/ so I guess it is fine. |
Hi, yes, I would like to remove Scala and use something more standard too. Tried first with Let me check if I can replace Scala with |
Maybe writing the entire script in Python is better than mixing languages. But your call, whatever works |
Hey, I think Kakoune is a great editor! I struggled with a searchable and mobile-phone friendly documentation. Here're a Bash and Scala scripts to use the existing `**/*.asciidoc` for generating the static website. The code is far from ideal, but should be a good start. Would be good to improve the script and automatically publish the documentation using Github Actions and Pages. Hosting the draft on my personal Github pages. Here's how it looks like: https://igor-ramazanov.github.io.
What: migrate from shell and Scala to pure Python. Why: to improve the UX as users likely already have Python installed.
@mawww @krobelus Hi, I've rewritten the script to Python 3. Now it does not depend on |
I dedicate any and all copyright interest in this software to the public domain. I make this dedication for the benefit of the public at large and to the detriment of my heirs and successors. I intend this dedication to be an overt act of relinquishment in perpetuity of all present and future rights to this software under copyright law.
6d326cd
to
08ccfaf
Compare
Refactoring: 1. Generate the docs from a single Python file. 2. Run through Blake formatter. 3. Add links to Antora documentation pages.
contrib/gendocs.py
Outdated
# See: https://docs.antora.org/antora/latest/standard-directories. | ||
# https://docs.antora.org/antora/latest/root-module-directory. | ||
os.makedirs("modules/ROOT/images", exist_ok=True) | ||
os.makedirs("modules/ROOT/pages", exist_ok=True) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
FWIW instead of doing an in-tree build that requires renaming of some files,
I'd prefer to creating a separate directory (html_doc
?),
copy all asciidoc files there and put all build artifacts there.
Not renaming files avoids confusing editors etc.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@krobelus Hey, long time. I've finally did that, now it keeps everything in the doc_gen
dir without modifying the worktree.
if "/" in fragmentless | ||
else (None, fragmentless) | ||
) | ||
return Link(path, file, fragment, title) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Actually GitHub is decent at rendering asciidoc, they also support the cross references.
Though the dedicated site definitely looks nicer and is more discoverable.
Maybe we can add a link to it on the website.
It does have a large overlap with github so I'm not sure it will gain a lot of momentum.
But it's nice to have a replacement we can custommize as we add more docs
contrib/gendocs.py
Outdated
# Finally, generate the documentation, | ||
# results will be saved to the output directory | ||
# as specified in the `antora-playbook.yml`. | ||
subprocess.run(["antora", "generate", "antora-playbook.yml"]) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
In addition to broken symlink, antora hangs indefinitely if there is a fifo in $PWD.
Also on a clean secondary worktree, it failed with
[23:39:47.976] FATAL (antora): Local content source must be a git repository: /home/johannes/git/kakoune2 (url: ./)
so it doesn't recognize that .git is a gitlink.
I'm not sure why it even interacts with Git.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@krobelus I'm not sure why it's been behaving like that,
but after keeping the work in the dedicated doc_gen/
I didn't have to remove the symlink,
so maybe this issue is gone now?
Could you verify it again, please?
* Instead of modifying files in-worktree, create a dedicated `doc_dir` directory to keep all the generated code and copy AsciiDoc there first. * Remove unnecessary deletion of a symbolical link at `libexec/kak`.
50cbb0c
to
6bc035f
Compare
Hey, I think Kakoune is a great editor!
I struggled with a searchable and mobile-phone friendly documentation.
Here're a Bash and Scala scripts to use the existing
**/*.asciidoc
for generating the static website.
The code is far from ideal, but should be a good start.
Would be good to improve the script and automatically publish the
documentation using Github Actions and Pages.
Hosting the draft on my personal Github pages.
Here's how it looks like: https://igor-ramazanov.github.io/.