Transition the Qubes documentation to the Read the Docs (RTD) platform

[andrewdavidwong]

Community devs: @maiska, @tokideveloper

Checklist:

• [ ] Complete conversion to Sphinx / RST (https://github.com/QubesOS/qubes-doc/pull/1367)
• [ ] Freeze docs
• [ ] Make testing announcement
• [ ] Wait for testing period to complete (2-4 weeks?)
• [ ] Incorporate any errors found, rerun conversion, and post final RTD version
• [ ] Make final announcement

---

Original issue text

The problem you're addressing (if any)

There are new and increasing demands on the documentation, the main two being localization (i.e., translations) and release-specific docs (https://github.com/QubesOS/qubes-issues/issues/5308). With these new demands, it has become increasingly difficult for the current system to meet our needs.

Back before we tried to address these kinds of needs, our documentation setup was simpler and served us well. The backend was smaller, easier to understand, and easier to maintain, since it didn't need to do much. There was only a single, canonical version of every documentation page.

However, times change. As our project has matured, we've decided it was time to acknowledge and take seriously the reality that not everyone reads English and not everyone uses the same version of Qubes OS at the same time. We have users and contributors from around the world, and we have multiple versions of Qubes.

There are times when an older Qubes release is supported concurrently with a newer release to give users time to upgrade. Even when there's only one currently-supported release, there's usually a new one in development and testing that folks want to start documenting. This means that we have to support a separate version of each appropriate documentation page for every translated language and for every supported and in-development Qubes version, not to mention historical documentation for EOL releases.

This is just a summary. In order to fully understand the context and background of this issue, please read the following mailing list threads:

1. https://www.mail-archive.com/[email protected]/msg04939.html
2. https://www.mail-archive.com/[email protected]/msg05011.html

The solution you'd like

Transition from the current system to the Read the Docs (RTD) platform (https://readthedocs.org, formerly https://readthedocs.io).

The value to a user, and who that user might be

• Built-in support for https://github.com/QubesOS/qubes-issues/issues/5308.
• Built-in localization support.
• Supports Git for version control and history.
• GitHub integration.
• Built-in support for downloading/exporting docs in multiple formats for offline reading. Direct access to human-readable source files in Git repos should also continue to be possible.
• Includes search functionality.
• Widespread use among open-source projects. Established history.
• Can be self-hosted.
• [Subjective] Some people think RTD looks better.

These will benefit those who produce and consume Qubes documentation.