Hi folks! Previously in the Summit, we talked about docs and how to better integrate existing documentation into our code bases and lower the contribution bar of editing docs for the wider community.
So, while the Summit is on-going, I put together a proof-of-concept of how inter-linked Sphinx documentation repos could work. This also comes from an infrastructure POV, how do we assemble and present those pieces in a clean and simple way to the community?
To demonstrate this, I created three GitHub repositories: a parent project and two “sub-projects.” Then I built all three of these on ReadTheDocs.org and connected the two sub-projects into the parent project. The parent project could be a “MetaBrainz” parent project, with other sub-projects (MusicBrainz, ListenBrainz, etc.) fitting underneath them. Fortunately, some of this is technically doable in MetaBrainz now even with our existing Sphinx/ReadTheDocs projects.
Here are URLs to three published docs sites:
- Parent: https://docs.thefutureis.science/en/latest/
- P.O.C. 1: https://docs.thefutureis.science/projects/poc-1/en/latest/
- P.O.C. 2: https://docs.thefutureis.science/projects/poc-2/en/latest/
All three of these repos are built from three separate sources:
If this is interesting, we can squeeze some time somewhere to look at this on Sunday before the Summit ends.
(BTW—the content on the two proof-of-concept docs sites were real docs taken from the wiki and converted to Markdown with zero changes by me. I left them as-is to show off the ease in how we can use a tool like Pandoc for quick conversion of MediaWiki into Markdown files. I’m working to automate that with this script I am putting together. Pandoc covers ~95% of the conversion and the other ~5% requires manual clean-up for things that do not convert nicely (e.g. internal wiki links and wiki category tags).