rpm-ostree
rpm-ostree copied to clipboard
coreos
Add full CLI documentation in GitHub pages
This is split from #2971. My initial impression was that for this to happen we needed to manually recreate the CLI man pages as markdown. However, after a brief conversation with @cgwalters he suggested that we could use some github automation to automatically convert the DocBook to html like currently is done to the docs page.
I don't see any support for anything other than markdown on github pages, we might need to look at how to convert the data automatically. In general the idea is to maintain a single source of truth for the CLI doc. WDYT @travier ?
I agree. Manually updating both the man pages and the docs on GitHub is not ideal.
My last attempt at doing automatic conversions have however been unsuccessful thus I settled on doing some manual updates while we figure this out. This is why for https://github.com/coreos/rpm-ostree/issues/2971 I think we should at least do the man pages and link a rendered version of them from the docs until we figure out how to auto convert.
See my comment in https://github.com/coreos/rpm-ostree/pull/3170#issuecomment-939864309
I used: https://github.com/ueberdosis/alldocs.app which is hosted on: https://alldocs.app/ to generate this https://github.com/coreos/rpm-ostree/pull/3272/files#diff-91cab257955ce52024a4473c290e8df59d542e46c8e58f16d2fce925c345baca markdown from the docbook and included it on my PR as a starting point. Maybe we can use something like what they are doing with pandoc in our pipeline in the future.
https://alldocs.app/convert-roff-man-to-commonmark > This one gives us the most stable output as far as I could see. The Direct DocBook to CommonMark had some artifacts.
This can probably be easily done in a GitHub Action or as one shot updates via a script that we call each time we do a doc update.
I think you can also create a man subfolder in the docs one where we can store the generated man pages, one page per manpage to organize things.
Honestly it may not be too bad to have a make docs-render that we just run manually as part of shipping a release.
In fact, it seems better to not have the Github web docs show things that just live in git main. (There's still a lag between a release and getting to users, but nothing we can do about that)
See also https://github.com/coreos/coreos-installer/pull/718 for inspiration (GitHub Action, etc.)