Convert all the documentation to Sphinx / RST - final version #1479
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This is done using tools at https://github.com/maiska/qubes-translation-utilz, commit 4c8e2a7f559fd37e29b51769ed1ab1c6cf92e00d.
Import only files used in the documentation (and their source files if applicable). Imported from https://github.com/QubesOS/qubes-attachment at 52bc8a22484236c5bd494707aafe32aa5e849950.
Manual fixes after the conversion tool. Mostly based on sphinx warnings.
This was referenced Jul 4, 2025
This is plain rename without changing content, to help git track files history. Do not touch files that are going to be removed during conversion. Thanks @parulin for the idea!
This is done using tools at https://github.com/maiska/qubes-translation-utilz, commit 4c8e2a7f559fd37e29b51769ed1ab1c6cf92e00d.
Import only files used in the documentation (and their source files if applicable). Imported from https://github.com/QubesOS/qubes-attachment at 52bc8a22484236c5bd494707aafe32aa5e849950.
Manual fixes after the conversion tool. Mostly based on sphinx warnings.
* Use dirhtml as default builder for readthedocs (clean URLs) * The configuration variables are now sorted with respect to the Sphinx documentation * Remove useless comments in conf.py * Add new comments for each section, following Sphinx documentation order * The code corresponding to videos have been moved from config to a dedicated extension. * Use proper HTML theme options * Exclude all files starting with `.`, `_` (sphinx convention) * Use OpenSearch
* Avoid checking .onion domains. * Do not download links to check anchors
RTD provides own CI service
Changing `bash` lexer to `console` because it is appropriate most of the time. Then after a manual review, some lexer have been changed. I used `text` each time I was unsure, and for prompt outputs. The page `/developer/building/qubes-iso-building.rst` still need to be reviewed (look for lines starting with `$ #`). I'm not sure about the Windows pages, should we use [doscon](https://pygments.org/docs/lexers/#pygments.lexers.shell.MSDOSSessionLexer) or `powershell`? Is there an appropriate lexer for `guid.conf` content? **Statistics - Before** 870 bash 9 python 9 c 2 yaml **Statistics - After** 684 console 111 text 44 bash 16 yaml 9 systemd 9 c 8 python 4 ini 4 doscon 2 markdown 2 desktop 1 xorg.conf 1 xml+jinja 1 xml 1 kconfig 1 html This suggests that the default lexer should be `console`.
* Most of text blocks are in fact output blocks
* On qubes-iso-building.rst, try to get something correct for console
lines starting with a comment
* Fixing a wrong :menuselection: item.
Statistics:
685 console
79 text
44 bash
35 output
16 yaml
9 systemd
9 c
8 python
4 ini
4 doscon
2 markdown
2 desktop
1 xorg.conf
1 xml+jinja
1 xml
1 kconfig
1 html
See issue 8180.
Thanks to @tokideveloper !!!
All raw directives have been removed or replaced by reStructuredText list-tables.
…nore add prompts to terminal sessions where needed
Once again, a valuable piece of documentation lost in the internet...
… website style guide in Markdown
…rkdown and website style guide docs
… combine website and markdown-style-guide, enhance how-to-edit-the-rst-documentation and rst style guide, fix errors, added comments to conf.py, links to README & CONTRIBUTING
….toml, alt text to images
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
7 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This is result of running https://github.com/maiska/qubes-translation-utilz/tree/main/md2rst on the documentation repo, developed by @maiska and @tokideveloper over last several months (years?). There is little sense in reviewing all the pages manually, but some selective sanity check could be useful.
It is now published at https://doc.qubes-os.org.
While restructuring qubes-doc repo, I'm merging also qubes-attachment repository into qubes-doc (or rather: importing files that are actually used here). The current approach with separate repos makes doc contribution with images very cumbersome, and since moving away from Trac several years ago there is no real reason for this split.
The conversion process is scripted, so it isn't big deal to re-run when needed (for example after merging some other PR in this repo), but I'd prefer to merge this soon anyway, to not diverge content too much. PRs that are currently open (if applicable) can be converted by the script on a side branch and then re-opened into RST version.
This replaces #1367