Add a contrib/gendocs.py script for generating documentation web site #4997
Conversation
igor-ramazanov
force-pushed
the
contrib/gendocs.sh
branch
from
11bd96f
to
1108634
Compare
igor-ramazanov
changed the title
|
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.
igor-ramazanov
force-pushed
the
contrib/gendocs.sh
branch
from
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.
igor-ramazanov
changed the title
| # 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.
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.
| if "/" in fragmentless | ||
| else (None, fragmentless) | ||
| ) | ||
| return Link(path, file, fragment, title) |
There was a problem hiding this comment.
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
| # 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.
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.
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
**/*.asciidocfor 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/.