flatpak-docs
flatpak-docs copied to clipboard
flatpak
Move to a different system for managing documentation
Currently, the documentation converts everything to HTML for use. I would suggest switching to a different system where you can use multiple formats for writing out the documentation.
I've given Jekyll a try, and I find it to be easier to manage than how the Flatpak docs work where you write them out in rst. Jekyll also has a number of plugins and such for other document formats, so it could be dropped in and reuse the current rst files rather than rewriting them.
It doesn't sound that valuable honestly. Why do we care about multiple formats?
I find it easier to manage guides and such in a language such as markdown, as rst doesn't feel fit for the job.
Aside from using multiple formats, Jekyll might also allow for easier doc editing, as it can reload a page while the server is running.
My current complaints with our readthedocs.org solution:
- Translations are a PITA
- Managing anything outside of this repo is annoying, duplicates permissions, etc
So I can see some value if we can set up a solution hosted here with github pages. Can you investigate how translations would work with Jekyll?
Also just something I worry could cause problems.
We copy-paste in our API documentation and it "just works":
- https://github.com/flatpak/flatpak-docs/blob/master/docs/libflatpak-docs.html
- https://docs.flatpak.org/en/latest/libflatpak-api-reference.html
I don't think its impossible but just documenting it here. If any transition were to happen all existing URLs should stay valid.
So I can see some value if we can set up a solution hosted here with github pages. Can you investigate how translations would work with Jekyll?
I can try, and a quick google search gives me this, which might be useful: https://talk.jekyllrb.com/t/translating-the-pages-to-other-languages/2049/3 I'm not experienced in anything other than english, so I probably can't help on that topic, but I can try, at least.
Small update -- maybe this would help a bit: https://simpleen.io/blog/translate-markdown-files
This all seems a bit more complicated than the current solution.
For now I'm going to close this as I don't think there is much of a compelling force.
If you find something truly compelling maybe it can be reconsidered if you want to help with the effort.