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

[andrewdavidwong]

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 (#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/qubes-devel@googlegroups.com/msg04939.html
2. https://www.mail-archive.com/qubes-devel@googlegroups.com/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 Release-specific documentation #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.

Completion criteria checklist:

• Complete conversion to Sphinx / RST
• Freeze docs
• Make testing announcement
• Wait for testing period to complete (2025-08-12)
• Incorporate any errors found, rerun conversion, and post final RTD version
• Create an RST guide for documentation contributors
• Officially replace old docs with new docs (Replace _doc submodule with redirects to rtd site qubesos.github.io#243)
• Make final announcement (Announcement: The Qubes documentation has successfully migrated to Read the Docs! qubes-posts#151)

Full list of documentation pages to be reviewed during testing period

For each documentation page in the list below:

• new denotes a link to the new documentation page (generated from reStructuredText and hosted by Read the Docs) that needs to be reviewed.

• old denotes a link to the old documentation page (generated from Markdown and hosted by GitHub Pages) so that you can compare the new page to the old one.

• source denotes a link to the reStructuredText source code for the new page, which is provided in case you want to open a pull request.

• Documentation index: new, old, source

• Release schedules: new, old, source

• Release notes: new, old, source

• Version scheme: new, old, source

• Release checklist: new, old, source

• Qubes R3.2 release schedule: new, old, source

• Qubes R3.2 release notes: new, old, source

• Qubes R4.2 release schedule: new, old, source

• Qubes OS 4.2 release notes: new, old, source

• Qubes R3.1 release schedule: new, old, source

• Qubes R3.1 release notes: new, old, source

• Qubes R3.0 release schedule: new, old, source

• Qubes R3.0 release notes: new, old, source

• Qubes R4.1 release schedule: new, old, source

• Qubes OS 4.1 release notes: new, old, source

• Qubes R1.0 release notes: new, old, source

• Qubes R2.0 release notes: new, old, source

• Qubes R4.0 release schedule: new, old, source

• Qubes R4.0 release notes: new, old, source

• Package contributions: new, old, source

• Developer books: new, old, source

• Continuous integration (CI): new, old, source

• Usability & UX: new, old, source

• Developing Qubes OS GUI tools: new, old, source

• Google Season of Docs (GSoD): new, old, source

• Research: new [*], old, source

• Google Summer of Code (GSoC): new, old, source

• Qubes builder v2: new, old, source

• Qubes ISO building: new, old, source

• Qubes builder details: new, old, source

• Qubes builder: new, old, source

• Development workflow: new, old, source

• Code signing: new, old, source

• Software license: new, old, source

• Source code: new, old, source

• Coding style: new, old, source

• Safe remote dom0 terminals: new, old, source

• Automated tests: new, old, source

• Windows debugging: new, old, source

• Qube configuration interface: new, old, source

• How to mount LVM images: new, old, source

• How to set up a test bench: new, old, source

• Qrexec v2 (deprecated): new, old, source

• Qrexec: Qubes RPC internals: new, old, source

• Qrexec: socket-based services: new, old, source

• Admin API: new [*], old, source

• Disposable implementation: new, old, source

• Qfileexchgd (deprecated): new, old, source

• Inter-qube file copying (qfilecopy): new, old, source

• Dom0 secure updates: new, old, source

• Qrexec: secure communication across domains: new, old, source

• Qubes memory manager (qmemman): new, old, source

• Security-critical code: new, old, source

• Template implementation: new, old, source

• Security design goals: new, old, source

• Passwordless root access in qubes: new, old, source

• Architecture: new, old, source

• Audio virtualization: new, old, source

• Networking: new, old, source

• GUI virtualization: new, old, source

• Template manager: new, old, source

• Xfce templates: new, old, source

• Minimal templates: new, old, source

• Templates: new, old, source

• Qubes Windows Tools (QWT): new, old, source

• Migrating Windows qubes to Qubes OS 4.1: new, old, source

• Windows qubes: new, old, source

• Qubes Windows Tools (QWT) in Qubes OS 4.0: new, old, source

• How to install Windows qubes in Qubes OS: new, old, source

• How to install Windows qubes in Qubes OS 4.0: new, old, source

• How to upgrade a Debian template in-place: new, old, source

• Debian templates: new, old, source

• How to upgrade a Fedora template in-place: new, old, source

• Fedora templates: new, old, source

• Suspend/resume troubleshooting: new, old, source

• Autostart troubleshooting: new, old, source

• Media troubleshooting: new, old, source

• USB troubleshooting: new, old, source

• Hardware troubleshooting: new, old, source

• Updating Debian and Whonix: new, old, source

• UEFI troubleshooting: new, old, source

• GUI troubleshooting: new, old, source

• App menu shortcut troubleshooting: new, old, source

• HVM troubleshooting: new, old, source

• Update troubleshooting: new, old, source

• Installation troubleshooting: new, old, source

• Disk troubleshooting: new, old, source

• VPN troubleshooting: new, old, source

• PCI troubleshooting: new, old, source

• Qube troubleshooting: new, old, source

• KDE (desktop environment): new, old, source

• Secondary storage: new, old, source

• Config files: new, old, source

• How to mount a Qubes partition from another OS: new, old, source

• Standalones and HVMs: new, old, source

• USB qubes: new, old, source

• How to install software in dom0: new, old, source

• Qubes service: new, old, source

• Managing qube kernels: new, old, source

• Installing contributed packages: new, old, source

• How to make any file persistent (bind-dirs): new, old, source

• Salt (management software): new, old, source

• AwesomeWM (window manager): new, old, source

• Volume backup and revert: new, old, source

• Resize disk image: new, old, source

• GUI configuration: new, old, source

• Disposable customization: new, old, source

• GUI domain: new, old, source

• RPC policies: new, old, source

• i3 (window manager): new, old, source

• Installation security: new, old, source

• Installation guide: new, old, source

• Qubes 4.1 Installation guide: new, old, source

• Testing new releases and updates: new, old, source

• Supported releases: new, old, source

• Download mirrors: new, old, source

• Upgrade guides: new, old, source

• How to upgrade to Qubes 4.1: new, old, source

• Upgrading to R2B3: new, old, source

• Upgrading to R4.0: new, old, source

• How to upgrade to Qubes 4.2: new, old, source

• Upgrading to R3.1: new, old, source

• Upgrading to R2B1: new, old, source

• Upgrading to R3.2: new, old, source

• Upgrading to R3.0: new, old, source

• Upgrading to R2B2: new, old, source

• Upgrading to R2: new, old, source

• How to use devices: new, old, source

• How to organize your qubes: new, old, source

• How to reinstall a template: new, old, source

• How to install software: new, old, source

• Emergency backup recovery (v3): new, old, source

• How to back up, restore, and migrate: new, old, source

• How to enter fullscreen mode: new, old, source

• How to copy from dom0: new, old, source

• How to copy and paste text: new, old, source

• Emergency backup recovery (v4): new, old, source

• How to use optical discs: new, old, source

• How to use block storage devices: new, old, source

• Emergency backup recovery (v2): new, old, source

• How to copy and move files: new, old, source

• How to update: new, old, source

• How to use USB devices: new, old, source

• How to use disposables: new, old, source

• How to use PCI devices: new, old, source

• System requirements: new, old, source

• How to use the hardware compatibility list (HCL): new, old, source

• NitroPC Pro: new, old, source

• Insurgo PrivacyBeast X230: new, old, source

• Star Labs StarBook: new, old, source

• NovaCustom V56 Series: new, old, source

• NitroPad X230: new, old, source

• NovaCustom V54 Series: new, old, source

• Certified hardware: new, old, source

• NitroPC Pro 2: new, old, source

• NitroPad T430: new, old, source

• NovaCustom NV41 Series: new, old, source

• NitroPad V56: new, old, source

• Dasharo FidelisGuard Z690: new, old, source

• Data leaks: new, old, source

• Device handling security: new, old, source

• Firewall: new, old, source

• Passwordless root access in qubes: new, old, source

• Anti evil maid (AEM): new, old, source

• Split GPG-2: new, old, source

• CTAP proxy: new, old, source

• Multi-factor Login: new, old, source

• Split GPG: new, old, source

• Firewall 4.1: new, old, source

• Command-line tools: new, old, source

• Glossary: new, old, source

• Verifying signatures: new, old, source

• Qubes OS project security center: new, old, source

• Qubes security pack (qubes-secpack): new, old, source

• Statistics: new, old, source

• How to contribute: new, old, source

• Privacy policy: new, old, source

• Frequently asked questions (FAQ): new, old, source

• Screenshots: new, old, source

• Introduction: new [*], old, source

• Help, support, mailing lists, and forum: new, old, source

• Code of conduct: new, old, source

• Getting started: new, old, source

• Issue tracking: new, old, source

• Video tours: new [*], old, source

[*] These pages were created manually rather than being processed automatically and may merit extra scrutiny.