Convert all the documentation to Sphinx / RST #1367

marmarek · 2024-01-05T13:17:59Z

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.

Currently the site is pushed to https://qubes-doc-rst.readthedocs.io/en/latest/index.html, but when agreed, I'd put it on https://doc.qubes-os.org (I'll simply configure it as a custom domain on the readthedocs hosting).

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.

marmarek · 2024-01-05T13:26:18Z

[ ] update external documentation links in the index

Actually, the current (github pages) doc index still points at the qubes-community github org. So, technically the rst index linking to qubes-community is not a regression, and can be fixed in a followup PR. I'd prefer it this way, to not block this huge conversion any longer.

tokideveloper

I went through all options on https://docs.readthedocs.io/en/stable/config-file/v2.html and consider the configuration file .readthedocs.yaml fine.
I don't know how the file requirements.txt has been written but I guess it has happened via something like pip freeze > requirements.txt.
The files README.md and CONTRIBUTING.md have been deleted without a replacement. I'm not sure whether a replacement is needed or not.
I checked the file conf.py, see my comments there.
I did not check the files of the converted documentation.
In general, a new run of converting the files to RST is needed. After that, I will re-review the files ASAP.

tokideveloper · 2024-05-20T13:56:36Z

conf.py

+source_suffix = {
+    '.rst': 'restructuredtext',
+}
+templates_path = ['_templates']


there is no file nor directory named _templates

tokideveloper · 2024-05-20T13:57:54Z

conf.py

+    'visitedlinkcolor': '#7b7b7b',
+    'bodyfont': '"Open Sans", Arial, sans-serif',
+    'codebgcolor': '$color-qube-light',
+    'codebgcolor': 'grey',


codebgcolor is set twice

tokideveloper · 2024-05-20T13:57:57Z

conf.py

+
+
+locale_dirs = ['_translated']
+


the option nitpicky = True could be useful, I think

the option language = 'en' could be set explicitly

the option language = 'en' could be set explicitly

Won't that interfere with language set in readthedocs?

the option language = 'en' could be set explicitly

Won't that interfere with language set in readthedocs?

I don't know. In the last minutes, I tried to find an answer on the Internet but without success. However, since language defaults to en, we can omit it.

marmarek · 2024-05-20T14:15:39Z

Thanks for checking @tokideveloper !
I'll do new run later today.

Import only files used in the documentation (and their source files if applicable). Based on c3f45c81842d6c5df064fce385b464b4041b3b62 in qubes-attachment repo.

Manual fixes after the conversion tool.

Not only comment them, really remove.

marmarek · 2024-05-21T20:13:18Z

Updated

tokideveloper · 2024-05-23T17:20:46Z

Updated

Thanks, @marmarek! @maiska wants to review my review and/or review the result with me this weekend. Hope that it can wait so long.

tokideveloper · 2024-05-23T19:19:20Z

Will there be an announcement about the migration to ReadTheDocs and ReST?

Concerning ReST, essentially the documentation style guide needs to be edited.

andrewdavidwong · 2024-05-23T20:59:50Z

Will there be an announcement about the migration to ReadTheDocs and ReST?

Sure, we can make an announcement about it. Are we close to launch?

tokideveloper · 2024-05-24T05:52:44Z

Are we close to launch?

I would say yes but I want to wait for this weekend (probably within 30 hours). When everything goes fine I will tell you here. Immediately afterwards the announcement can come and then let's say 3 days until launch? Just to see the reactions beforehand.

Hope that the Markdown version on qubes-doc won't diverge too much meanwhile.

andrewdavidwong · 2024-05-24T21:05:08Z

Immediately afterwards the announcement can come and then let's say 3 days until launch? Just to see the reactions beforehand.

You want to announce it before it's live in order to see people's reactions beforehand? Are you thinking that people will somehow figure out how to preview it themselves and effectively beta test it so that we can abort the launch if there are big problems? The problem is that we will have already announced it by that point, so it will kind of be too late. If we're afraid that testing might reveal big problems, we should just have some kind of designated testing period first.

tokideveloper · 2024-05-25T05:46:57Z

You want to announce it before it's live in order to see people's reactions beforehand? Are you thinking that people will somehow figure out how to preview it themselves and effectively beta test it so that we can abort the launch if there are big problems? The problem is that we will have already announced it by that point, so it will kind of be too late. If we're afraid that testing might reveal big problems, we should just have some kind of designated testing period first.

I never thought about users being beta testers for the documentation. I'm just curious to see how people react when they know what's coming just based on the description. But maybe it's pointless and probably stupid the more I think about it. I'm sorry for my bad idea!

However, an announcement itself would be fine IMHO. I'll let you know when it's time for it. Thank you!

tokideveloper · 2024-05-25T16:55:50Z

@marmarek wrote:

There is little sense in reviewing all the pages manually, but some selective sanity check could be useful.

I thought that, too, but now, I started reviewing all the pages manually by comparing the rendered Markdown pages and the rendered ReST pages side by side and I've found a lot of errors (and I'm not done yet). This includes:

dropped links, especially in “Warning” boxes etc.,
dropped formattings, especially in “Warning” boxes etc.,
messed up lists, tables and codeblocks.

I'm making a list of all those errors and will correct them afterwards.

maiska · 2024-05-25T17:54:30Z

index.rst

-^^^^^^^^^^^^^^^^^
-
+   :caption: Troubleshooting
+


QA: in the original index the order is as follows here under Security in Qubes section:
Multi-factor Login
CTAP proxy

maiska · 2024-05-25T17:56:13Z

index.rst

 Core documentation for Qubes developers and advanced users.

-General
-^^^^^^^
-


The section name in the oirignal is General not Developers - General. if the section is named _general? similar to the rest subsections in the Developer Documentation

This is intentional, so the TOC on the left is clearer, otherwise it easy to miss which sections belong to developers and which to users documentation.

maiska · 2024-05-25T17:58:32Z

index.rst

 Unofficial, third-party documentation from the Qubes community and
 others.

-Operating System Guides
-^^^^^^^^^^^^^^^^^^^^^^^
-


The same for the subsection to the External Documentation as in the comment about the Developer Documentaion

tokideveloper · 2024-05-25T18:14:01Z

These are errors I've found so far (sorry for writing it in German):

https://qubes-doc-rst.readthedocs.io/en/latest/introduction/intro.html

C Note unterm ersten Bild: nicht eingerahmt und blau und die Links fehlen
C Note am Ende des Abschnitts „Features“: dito.
? Abschnitt „Made to support vulnerable users and power users alike“: „you“ und „must“ sind fett statt kursiv.

https://qubes-doc-rst.readthedocs.io/en/latest/introduction/screenshots.html

M Auf den Satz „This feature requires Intel VT-d or AMD IOMMU hardware (e.g., Core i5/i7 systems)“ folgen störende „* * * * *“.

https://qubes-doc-rst.readthedocs.io/en/latest/introduction/getting-started.html

C Im Satz „The Whonix SDWDate allows you to control the Tor connection in your sys-whonix qube.“ ist „sys-whonix“ nicht in dicktengleicher Schrift.
M Im Satz „Press Alt+F3 and search for xfce terminal.“ ist „Alt+F3“ nicht getrennt in „Alt“, „+“ und „F3“.

https://qubes-doc-rst.readthedocs.io/en/latest/introduction/faq.html

? Im Abschnitt „How does Qubes OS compare to using a separate physical machine?“ wurden die Aufzählungstitel „Pros“ und „Cons“ schlecht konvertiert.
C Im Abschnitt „What about this other/new (micro)kernel/hypervisor?“ ist das „TM“ ganz unten im Abschnitt nicht hochgestellt.
M, content Im Abschnitt „Should I trust this website?“ wird ReadTheDocs nicht erwähnt.

https://qubes-doc-rst.readthedocs.io/en/latest/introduction/issue-tracking.html

? In der Aufzählung „Meta-issues must abide by the following rules:“ soll in den ersten beiden Aufzählungspunkten jeweils vor „Rationale“ eine Leerzeile bzw. Paragraphabschnitt stehen.
M Im Abschnitt „Search tips“ ist in der Aufzählung vor dem letzten Punkt eine unnötige Leerzeile.
C Im Satz mit „In GitHub, an issue can be closed as either“ ist die Formatierung von „completed“ misslungen.

https://qubes-doc-rst.readthedocs.io/en/latest/introduction/support.html

C Im Abschnitt „I have a problem or a question.“ ist in der Aufzählung im 5. Punkt das „qubes-users“ nicht in dicktengleicher Schrift.
C Im Abschnitt „I didn’t find a solution or an answer!“ dito.
C Im Abschnitt „Where’s the best place to discuss Qubes?“ dito.
? Im Abschnitt „Social media“ fehlen die Links in der Aufzählung.
M Im Abschnitt „Chat“ ist die Aufzählung kaputt.

https://qubes-doc-rst.readthedocs.io/en/latest/user/hardware/system-requirements.html

C Im ersten Warning-Block ist „necessary, but not sufficient“ nicht kursiv und der Link „resources below“ fehlt.

https://qubes-doc-rst.readthedocs.io/en/latest/user/hardware/certified-hardware.html

C Im ersten Danger-Block fehlen mehrere Kursiv-Formatierungen.

https://qubes-doc-rst.readthedocs.io/en/latest/user/downloading-installing-upgrading/installation-guide.html

C Im ersten und zweiten Danger-Block fehlt der Link „installation security“.
C Im ersten Warning-Block fehlt die Hervorhebung von „nested virtualization“.
C Im zweiten Warning-Block fehlen zwei Links.
C Im ersten Note-Block fehlt ein Link.
? Im Abschnitt „Installation summary“ ist der erste Note-Block blau statt grün.
C Im Abschnitt „Installation destination“ fehlen im ersten Warning-Block Kursiv-Formatierungen.
C Im Abschnitt „Installation destination“ fehlen im ersten Note-Block ein Link und eine Formatierung.

https://qubes-doc-rst.readthedocs.io/en/latest/user/downloading-installing-upgrading/testing.html

C Der schwebende Caution-Block fehlt: „Caution: This page is intended for advanced users.“.
? Im Abschnitt „Providing feedback“ fehlen die Symbole für „Daumen-hoch“ und „Daumen-runter“.

https://qubes-doc-rst.readthedocs.io/en/latest/user/how-to-guides/how-to-update.html

C Im Abschnitt „Security updates“ ist „qubes-secpack“ nicht dicktengleich formatiert.
C Im ersten Note-Block fehlen zwei Links.
C Im Abschnitt „AEM resealing after updating“ ist „README“ nicht dicktengleich formatiert.
C Im Abschnitt „Command-line interface“ sind im ersten Danger-Block Formatierungen falsch und ein Link fehlt.

https://qubes-doc-rst.readthedocs.io/en/latest/user/how-to-guides/backup-emergency-restore-v3.html

C In Punkten 3, 5, und 10 sind manche Notes im selben Paragraph statt in getrennten.

https://qubes-doc-rst.readthedocs.io/en/latest/user/how-to-guides/backup-emergency-restore-v4.html

C In Punkten 6 und 8 sind die Notes nicht abgesetzt.

https://qubes-doc-rst.readthedocs.io/en/latest/user/how-to-guides/how-to-copy-from-dom0.html

? Im Titel „Copying from dom0“ ist „from“ nicht fett hervorgehoben.
? Im Titel „Copying to dom0“ ist „to“ nicht fett hervorgehoben.

https://qubes-doc-rst.readthedocs.io/en/latest/user/how-to-guides/how-to-install-software.html

C Im Satz „Make sure you restart your app qube after shutting down your template.“ ist „after“ nicht kursiv.
C Im Satz „This command will roll back any changes made during the last time the template was run, but not before.“ ist „not“ nicht kursiv.
M Im Abschnitt „Autostarting Installed Applications“ ist der Befehl „ls /usr/share/applications“ wegen zu vieler Leerzeichen schlecht formatiert.

https://qubes-doc-rst.readthedocs.io/en/latest/user/how-to-guides/how-to-use-disposables.html

C Im Abschnitt „Example of RPC policies to allow this behavior“ ist die Aufzählung schlecht formatiert.

https://qubes-doc-rst.readthedocs.io/en/latest/user/how-to-guides/how-to-use-devices.html

C Im Abschnitt „Introduction“ ist die Aufzählung schlecht formatiert.

https://qubes-doc-rst.readthedocs.io/en/latest/user/how-to-guides/how-to-use-block-storage-devices.html

C Im Abschnitt „Block Devices in VMs“ ist der Link „frontend-dev-option“ unzureichend formatiert.

https://qubes-doc-rst.readthedocs.io/en/latest/user/how-to-guides/how-to-use-usb-devices.html

M „sys-usb:2-5 - 058f_USB_2.0_Camera“ ist schlecht formatiert.
C Der Link im Satz „Strip the address and pass it to the qvm-pci tool to attach the controller to the targetVM.“ ist unzureichend formatiert.

https://qubes-doc-rst.readthedocs.io/en/latest/user/how-to-guides/how-to-use-pci-devices.html

C Im Abschnitt „Attaching Devices Using the GUI“ ist Punkt 1.1 schlecht formatiert.
? Im Satz „The qvm-pci tool allows PCI attachment and detachment. It’s a shortcut for qvm-device pci“ ist „qvm-device pci“ nicht dicktengleich formatiert. Außerdem fehlt das Satzendezeichen.

https://qubes-doc-rst.readthedocs.io/en/latest/user/how-to-guides/how-to-reinstall-a-template.html

C Im Abschnitt „Manual Method“ fehlen in der Aufzählung Absätze.

https://qubes-doc-rst.readthedocs.io/en/latest/user/templates/minimal-templates.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.

https://qubes-doc-rst.readthedocs.io/en/latest/user/templates/templates.html

? Tabelle: Links fehlen und Formatierungen auch.
C Im Satz „Dom0 compromise is absolutely fatal, and it leads to Game OverTM.“ ist „TM“ nicht hochgestellt.

https://qubes-doc-rst.readthedocs.io/en/latest/user/templates/fedora/fedora-upgrade.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.
C Links fehlen im ersten Danger-Block.

https://qubes-doc-rst.readthedocs.io/en/latest/user/templates/debian/debian-upgrade.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.
C Links fehlen im ersten Danger-Block.
M Im Abschnitt „Debian 9 (“Stretch”)“ haben zwei dicktengleiche Teile überflüssige Leerzeichen.

https://qubes-doc-rst.readthedocs.io/en/latest/user/templates/windows/windows-qubes-4-1.html

C Im Abschnitt „Windows VM installation“ ist die erste Aufzählung schlecht formatiert.
C Im Abschnitt „Create Windows VM“ ist die Aufzählung sehr schlecht formatiert.
? In der Aufzählung „These parameters are set for the following reasons:“ ist der Punkt 3 sehr schlecht formatiert (Codeblock).
? Im Abschnitt „Start Windows VM“ ist Punkt 1 der Aufzählung sehr schlecht formatiert (Codeblock).
M Im Abschnitt „Start Windows VM“ ist bei Punkt 2 der Aufzählung der Warning-Block schlecht formatiert (auch in der Markdown-Version!).
M Im Punkt „On systems shipped with a Windows license, the product key may be read from flash via root in dom0:“ ist der nachfolgende Befehl nicht in einem abgesetzten Codeblock (ähnlich auch in der Markdown-Version).
? Im Abschnitt „After Windows installation“ ist der Codeblock falsch formatiert.
C Der Satz „At this point you may open a tab in dom0 for debugging, in case something goes amiss:“ ist nicht abgesetzt.
C Im Abschnitt „Windows as a template“ sind zwei Codeblöcke falsch formatiert.

https://qubes-doc-rst.readthedocs.io/en/latest/user/templates/windows/qubes-windows-tools-4-1.html

https://qubes-doc-rst.readthedocs.io/en/latest/user/templates/windows/migrate-to-4-1.html

C Im Abschnitt „Preparation for Windows 10 and 11“ ist die Aufzählung kaputt.

https://qubes-doc-rst.readthedocs.io/en/latest/user/troubleshooting/installation-troubleshooting.html

? Im Abschnitt „“Not asking for VNC because we don’t have a network” / “X startup failed, aborting installation” / “Pane is dead” error during installation“ sind die Codeblöcke kaputt.

https://qubes-doc-rst.readthedocs.io/en/latest/user/security-in-qubes/firewall.html

? Im Satz „For details of that usage see here“ führt der Link zu readthedocs, aber 404. Wurde die verlinkte Seite nicht gerendert?
M Im Satz „Opening a single TCP port to other network-isolated qube“ ist eine Note falsch formatiert.

https://qubes-doc-rst.readthedocs.io/en/latest/user/security-in-qubes/data-leaks.html

C Im Abschnitt „Types of Data Leaks“ ist der Satz (und folgende) nicht abgesetzt: „Both Qubes firewall and an empty NetVM …“

https://qubes-doc-rst.readthedocs.io/en/latest/user/security-in-qubes/vm-sudo.html

? Der Satz „| Passwordless root is provided by the qubes-core-agent-passwordless-root package. |“ hat die Pipes zuviel.

EDIT: markers added

EDIT 2: checkboxes added

tokideveloper · 2024-05-25T18:21:16Z

The previous post is especially for @maiska 🙂

andrewdavidwong · 2024-05-25T19:48:04Z

I never thought about users being beta testers for the documentation. I'm just curious to see how people react when they know what's coming just based on the description.

Ah, I see. I guess it depends on how detailed of a description you have in mind, but we've already been telling people that the migration to RtD is coming for over a year now, so there have already been lots of reactions (e.g., on the forum and mailing lists).

But maybe it's pointless and probably stupid the more I think about it. I'm sorry for my bad idea!

Not at all! I just wasn't quite sure what you had in mind. Sorry if my remarks came across negatively.

I think it's good that you highlighted the importance of getting feedback from our real userbase. The more I think about it, the more I think that a public testing period (where we ask people to test https://qubes-doc-rst.readthedocs.io/, for example) would be a good idea and might help the transition to go a lot smoother. People will inevitably discover and point out lots of problems that we'll have to fix, and it'd be a lot better to have that happen during a testing period than after launching the live, stable version. However, I'm not sure if we have the bandwidth to support that, and I wouldn't want to delay things even further. (@marmarek, do you have thoughts on this?)

However, an announcement itself would be fine IMHO. I'll let you know when it's time for it. Thank you!

Sounds good. :)

marmarek · 2024-05-25T21:12:50Z

@tokideveloper thanks for the review! I think the best approach to fix those issues is to separate them into following categories:

Issues present already in the source markdown version (like not closed quotes etc)
Repeatable issues due to converter limitation (links in warning boxes?)
Isolated issues in the converted pages (like a type of issue affecting only a single page)

The first one IMO best to fix in the markdown version (like I did at 7598bbe)
The second and third is more tricky - some may be better to fix in the converter tool, especially when there are several instances of a given issue, but others may be easier to manually fix on the ReST version already. Some cases are not obvious to which category they belong...

tokideveloper · 2024-05-26T05:05:40Z

@andrewdavidwong wrote:

I never thought about users being beta testers for the documentation. I'm just curious to see how people react when they know what's coming just based on the description.

Ah, I see. I guess it depends on how detailed of a description you have in mind, but we've already been telling people that the migration to RtD is coming for over a year now, so there have already been lots of reactions (e.g., on the forum and mailing lists).

Ah, okay, I didn't read them yet.

But maybe it's pointless and probably stupid the more I think about it. I'm sorry for my bad idea!

Not at all! I just wasn't quite sure what you had in mind. Sorry if my remarks came across negatively.

Often, I tell only half of my thoughts, not knowing that the other half is important, too. This often causes misunderstandings. I'm sorry for that.

For me, your remarks came across indeed a little bit negatively but that's not a reason for me not to reply in a professional way. 🙂

I think it's good that you highlighted the importance of getting feedback from our real userbase. The more I think about it, the more I think that a public testing period (where we ask people to test https://qubes-doc-rst.readthedocs.io/, for example) would be a good idea and might help the transition to go a lot smoother. People will inevitably discover and point out lots of problems that we'll have to fix, and it'd be a lot better to have that happen during a testing period than after launching the live, stable version. However, I'm not sure if we have the bandwidth to support that, and I wouldn't want to delay things even further. (@marmarek, do you have thoughts on this?)

Sounds good! However, we should correct the obvious problems first. Afterwards, the people may take a look and list problems they find (or open PRs for them). I'm not sure whether PR-ing new content should be allowed at this stage.

tokideveloper · 2024-05-26T05:07:12Z

@marmarek wrote:

@tokideveloper thanks for the review!

No problem. However, I'm not done yet. ;-)

I think the best approach to fix those issues is to separate them into following categories:
1. Issues present already in the source markdown version (like not closed quotes etc)

2. Repeatable issues due to converter limitation (links in warning boxes?)

3. Isolated issues in the converted pages (like a type of issue affecting only a single page)
The first one IMO best to fix in the markdown version (like I did at 7598bbe) The second and third is more tricky - some may be better to fix in the converter tool, especially when there are several instances of a given issue, but others may be easier to manually fix on the ReST version already. Some cases are not obvious to which category they belong...

Good idea! I can try to assign the issues to these categories by just guessing and hope that's the correct category for each one. We'll see …

tokideveloper · 2024-05-26T08:17:16Z

I'm done. Other issues I've found:

https://qubes-doc-rst.readthedocs.io/en/latest/user/security-in-qubes/split-gpg.html

C Im Abschnitt „Thunderbird 78 and higher“ ist der erste Absatz schlecht formatiert.
C? Im Abschnitt „Setup Description“ fehlen in der Tabelle die Formatierungen.
C Unter dieser Tabelle fehlen in der Aufzählung Absätze.

https://qubes-doc-rst.readthedocs.io/en/latest/user/security-in-qubes/mfa.html

C Im Abschnitt „Setup login with YubiKey / NitroKey3“ fehlen viele Absätze in der Aufzählung „Install YubiKey / NitroKey3 software in the template on which your USB VM is based.“.
M? Im Abschnitt „Optional: Locking the screen when YubiKey / NitroKey3 is removed“ ist die Nummerierung durcheinander.

https://qubes-doc-rst.readthedocs.io/en/latest/user/advanced-topics/how-to-install-software-in-dom0.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.

https://qubes-doc-rst.readthedocs.io/en/latest/user/advanced-topics/volume-backup-revert.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.

https://qubes-doc-rst.readthedocs.io/en/latest/user/advanced-topics/standalones-and-hvms.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.
C Im Abschnitt „Creating a standalone“ ist die Aufzählung kaputt.

https://qubes-doc-rst.readthedocs.io/en/latest/user/advanced-topics/config-files.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.
? Im Abschnitt „GUI and audio configuration in dom0“ fehlt im ersten Punkt der Liste ein Absatz.

https://qubes-doc-rst.readthedocs.io/en/latest/user/advanced-topics/secondary-storage.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.

https://qubes-doc-rst.readthedocs.io/en/latest/user/advanced-topics/rpc-policy.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.

https://qubes-doc-rst.readthedocs.io/en/latest/user/advanced-topics/usb-qubes.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.

https://qubes-doc-rst.readthedocs.io/en/latest/user/advanced-topics/managing-vm-kernels.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.
? Im Abschnitt „Installing different VM kernel based on dom0 kernel“ ist die Liste nach/in dem ersten Absatz kaputt.

https://qubes-doc-rst.readthedocs.io/en/latest/user/advanced-topics/salt.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.
C Im Abschnitt „Debugging“ ist die Aufzählung falsch formatiert.

https://qubes-doc-rst.readthedocs.io/en/latest/user/advanced-topics/gui-domain.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.

https://qubes-doc-rst.readthedocs.io/en/latest/user/advanced-topics/disposable-customization.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.

https://qubes-doc-rst.readthedocs.io/en/latest/user/advanced-topics/installing-contributed-packages.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.

https://qubes-doc-rst.readthedocs.io/en/latest/user/advanced-topics/bind-dirs.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.
? Im Abschnitt „What is it useful for?“ ist „/var/lib/tor“ nicht dicktengleich formatiert.
M? Im Abschnitt „Limitations“ fehlt im letzten Punkt beim Link „rw/config/rc.local“ ein vorangestelltes Slash. Außerdem muss dann „/rw/config/rc.local“ dicktengleich formatiert werden.

https://qubes-doc-rst.readthedocs.io/en/latest/user/advanced-topics/gui-configuration.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.

https://qubes-doc-rst.readthedocs.io/en/latest/user/advanced-topics/resize-disk-image.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.

https://qubes-doc-rst.readthedocs.io/en/latest/user/advanced-topics/qubes-service.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.

https://qubes-doc-rst.readthedocs.io/en/latest/user/advanced-topics/mount-from-other-os.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.
C Im Abschnitt „How to mount a Qubes partition from another OS“ ist die Liste kaputt.
CR? In der Tabelle ist in der ersten Spalte die Zelle mit „ot her_install/-private“ kaputt: Das Leerzeichen ist dort zuviel!

https://qubes-doc-rst.readthedocs.io/en/latest/user/advanced-topics/kde.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.

https://qubes-doc-rst.readthedocs.io/en/latest/user/advanced-topics/i3.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.

https://qubes-doc-rst.readthedocs.io/en/latest/user/advanced-topics/awesomewm.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.

https://qubes-doc-rst.readthedocs.io/en/latest/developer/general/gsoc.html

M Im Abschnitt „Secure Boot support“ sind zwei Aufzählungen kaputt.
M Im Abschnitt „Reduce logging of Disposable VMs“ ist eine Aufzählung kaputt.

https://qubes-doc-rst.readthedocs.io/en/latest/

? Der Link „How to edit the documentation“ führt zu qubes-os.org, nicht RtD. Soll das so sein?
? Der Link „Documentation style guide“ führt zu qubes-os.org, nicht RtD. Soll das so sein?
? Der Link „Website style guide“ führt zu qubes-os.org, nicht RtD. Soll das so sein?
? Der Link „Visual style guide“ führt zu qubes-os.org, nicht RtD. Soll das so sein?

https://qubes-doc-rst.readthedocs.io/en/latest/developer/general/usability-ux.html

M Die „Important“-Blöcke sollen eigentlich keine Blöcke sein.
M Unter „Minimize Repetitive Steps“ ist die Aufzählung „Navigate through file system“ nicht untergeordnet.

https://qubes-doc-rst.readthedocs.io/en/latest/developer/code/source-code.html

C Der Absatz „Opening a pull request on GitHub …“ ist nicht abgesetzt.

https://qubes-doc-rst.readthedocs.io/en/latest/developer/code/code-signing.html

M Im Abschnitt „Code Signature Checks“ sind die beiden Zitate in der Aufzählung falsch formatiert. Besser wäre es, sie in Backticks zu setzen, oder? Dann sollte es aber bei den anderen Zitaten auch gemacht werden.

https://qubes-doc-rst.readthedocs.io/en/latest/developer/services/qrexec2.html

? Der Titel „Qubes RPC internals“ ist zu klein geschrieben. Zu untersuchen.

https://qubes-doc-rst.readthedocs.io/en/latest/developer/services/qrexec-internals.html

C Es fehlen in den Listen die Absätze!

https://qubes-doc-rst.readthedocs.io/en/latest/developer/services/qrexec-socket-services.html

M Im Abschnitt „Example: qrexec-policy-agent“ ist die Liste falsch formatiert.

https://qubes-doc-rst.readthedocs.io/en/latest/developer/services/admin-api.html

C Im ersten Satz „You may also be interested in the article …“ fehlt nach „article“ ein Leerzeichen. Außerdem ist der Link nicht kursiv.

https://qubes-doc-rst.readthedocs.io/en/latest/developer/services/admin-api.html

? Im Abschnitt „The calls“ sind in der Tabelle manche Formatierungen verloren gegangen.

https://qubes-doc-rst.readthedocs.io/en/latest/developer/debugging/automated-tests.html

M Im Abschnitt „Looking for patterns in tests“ sind die Listen kaputt.

https://qubes-doc-rst.readthedocs.io/en/latest/developer/debugging/vm-interface.html

M Im Abschnitt „Qubes RPC“ ist die Liste unter „Caller sends name of requested icon. This can be one of:“ nicht ausreichend eingerückt.

https://qubes-doc-rst.readthedocs.io/en/latest/developer/building/qubes-builder.html

C Im „Warning“-Block fehlen ein Absatz und ein Link.
M Im Abschnitt „Manual source modification“ ist in der Liste der Punkt „You can also set GIT_PREFIX=“marmarek/qubes-” to use marmarek’s repo“ nicht ausreichend eingerückt.

https://qubes-doc-rst.readthedocs.io/en/latest/developer/building/qubes-builder-details.html

C Im „Warning“-Block fehlen ein Absatz und ein Link.

https://qubes-doc-rst.readthedocs.io/en/latest/developer/building/qubes-iso-building.html

C Im „Warning“-Block fehlen ein Absatz und ein Link.

https://qubes-doc-rst.readthedocs.io/en/latest/developer/releases/version-scheme.html

C Im Abschnitt „Release schedule“ fehlt in der Tabelle eine Formatierung.

EDIT: checkboxes added

tokideveloper · 2024-05-26T08:38:55Z

Here is the legend for the listed issues:

M: issue probably in Markdown file
C: issue probably during conversion
R: issue should be solved in the ReST file
?: don't know / to inspect / take a closer look

maiska · 2024-05-26T14:03:44Z

@tokideveloper and me are going to proceed with reviewing next weekend. FYI

unman · 2024-05-27T11:41:22Z

On Sun, May 26, 2024 at 07:04:08AM -0700, m wrote: @tokideveloper and me are going to proceed with reviewing next weekend. FYI

This is excellent. Possible steps to progress would be: 1. rerun the conversion after incorporating any errors found. 2. Freeze docs. 3. Post announcement about existence of RTD and invite comments, and further "eyes on" testing and review, for a set period. (2-4 weeks?) 4. Incorporate any errors found, rerun conversion, and post final RTD version. 5. Forward existing pages to RTD Thoughts?

marmarek · 2024-05-27T11:49:21Z

Post announcement about existence of RTD and invite comments, and further "eyes on" testing and review, for a set period. (2-4 weeks?)

I don't think this should be a full announcement on the website (this should be only for the actual switch when finally done), but maybe a mailing list post and a forum post (in the testing category)? I mean, the target audience here would be testers and contributors, not really all users (yet).

Forward existing pages to RTD

FYI for this part there is QubesOS/qubesos.github.io#243. I did not updated it this time, but the conversion tool can also generate this one, so it's just a matter of re-running it.

unman · 2024-05-27T12:08:28Z

On Mon, May 27, 2024 at 04:49:43AM -0700, Marek Marczykowski-Górecki wrote: I don't think this should be a full announcement on the website (this should be only for the actual switch when finally done), but maybe a mailing list post and a forum post (in the testing category)? I mean, the target audience here would be testers and contributors, not really all users (yet).

This was what I had originally drafted - I think that post should not be restricted to "testers", and there will be users who watch web site bit not Forum.

FYI for this part there is QubesOS/qubesos.github.io#243. I did not updated it this time, but the conversion tool can also generate this one, so it's just a matter of re-running it.

[/quote] Yes, I saw that. It's a step to take, not an added process. And we should add: 6. Make full new announcement

andrewdavidwong · 2024-05-28T02:22:12Z

I don't think this should be a full announcement on the website (this should be only for the actual switch when finally done), but maybe a mailing list post and a forum post (in the testing category)? I mean, the target audience here would be testers and contributors, not really all users (yet).

This was what I had originally drafted - I think that post should not be restricted to "testers", and there will be users who watch web site bit not Forum.

I think the bar for testing a website is a lot lower than for testing a Qubes OS release candidate, for example. Clicking around a website is low risk and doesn't require as much technical sophistication. I think it would be fine to announce the testing in a more general forum category (in addition to qubes-devel and qubes-users), but I agree with not doing a full announcement yet.

Forward existing pages to RTD

Does this mean forwarding to someplace on the readthedocs.io domain? Because my understanding is that the readthedocs.io domain is being used only for testing, whereas the final new documentation will live at https://doc.qubes-os.org/ (as mentioned in QubesOS/qubesos.github.io#243). Just making sure everyone is on the same page.

And we should add:
6. Make full new announcement

Thanks! I've updated QubesOS/qubes-issues#8180 and added a version of this checklist there.

tokideveloper · 2024-05-31T12:19:44Z

I missed some files. This should be the rest:

https://qubes-doc-rst.readthedocs.io/en/latest/user/downloading-installing-upgrading/installation-guide-4.1.html

C In allen Blöcken fehlen Formatierungen und/oder Links.

https://qubes-doc-rst.readthedocs.io/en/latest/user/security-in-qubes/firewall_4.1.html

M Im Abschnitt „Opening a single TCP port to other network-isolated qube“ ist in der Aufzählung eine Note falsch formatiert.
M Im Abschnitt „Port forwarding to a qube from the outside world“ sind in der Aufzählung fünf Noten falsch formatiert.

https://qubes-doc-rst.readthedocs.io/en/latest/user/templates/windows/qubes-windows-tools-4-0.html

R Im Abschnitt „Configuration“ fehlen in der ersten Tabelle die Backslashes.
C? Im Abschnitt „Configuration“ ist die zweite Tabelle schlecht formatiert.

https://qubes-doc-rst.readthedocs.io/en/latest/user/templates/windows/windows-qubes-4-0.html

M Im Abschnitt „Simple Windows install“ ist die Aufzählung schlecht formatiert.
M Im Abschnitt „Windows as a template“ sind zwei Codeblöcke schlecht formatiert.

maiska · 2024-06-01T10:46:39Z

This is WIP, and will mark here when I am done. But see rolling comments below.
Created a fork from main qubes-doc repo to add changes from here into markdown where needed
will mark minor problems, that are nice to fix but not must, as a LATER TODO, to add to a list, for when the rst documentation is online.

These are errors I've found so far (sorry for writing it in German):

https://qubes-doc-rst.readthedocs.io/en/latest/introduction/intro.html

C Note unterm ersten Bild: nicht eingerahmt und blau und die Links fehlen

links are fixed,
framing and color - LATER TODO

C Note am Ende des Abschnitts „Features“: dito.

see above

? Abschnitt „Made to support vulnerable users and power users alike“: „you“ und „must“ sind fett statt kursiv.

see https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html. It is either bold or italic. Better bold imho

https://qubes-doc-rst.readthedocs.io/en/latest/introduction/screenshots.html

M Auf den Satz „This feature requires Intel VT-d or AMD IOMMU hardware (e.g., Core i5/i7 systems)“ folgen störende „* * * * *“.

fixed that in the fork

https://qubes-doc-rst.readthedocs.io/en/latest/introduction/getting-started.html

C Im Satz „The Whonix SDWDate allows you to control the Tor connection in your sys-whonix qube.“ ist „sys-whonix“ nicht in dicktengleicher Schrift.

LATER TODO

M Im Satz „Press Alt+F3 and search for xfce terminal.“ ist „Alt+F3“ nicht getrennt in „Alt“, „+“ und „F3“.

LATER TODO

https://qubes-doc-rst.readthedocs.io/en/latest/introduction/faq.html

? Im Abschnitt „How does Qubes OS compare to using a separate physical machine?“ wurden die Aufzählungstitel „Pros“ und „Cons“ schlecht konvertiert.

fixed

C Im Abschnitt „What about this other/new (micro)kernel/hypervisor?“ ist das „TM“ ganz unten im Abschnitt nicht hochgestellt.

CONFIGURATION TODO, should be fixed in the code of the parser, but it is much easier to change the configuration
with a blunt exchange, DONE, see also https://docutils.sourceforge.io/docs/ref/rst/roles.html#superscript

M, content Im Abschnitt „Should I trust this website?“ wird ReadTheDocs nicht erwähnt.

CONTENT TODO: two sections: Should I trust the Qubes OS official website and one for RTD -> create a github issue/pull request

https://qubes-doc-rst.readthedocs.io/en/latest/introduction/issue-tracking.html

? In der Aufzählung „Meta-issues must abide by the following rules:“ soll in den ersten beiden Aufzählungspunkten jeweils vor „Rationale“ eine Leerzeile bzw. Paragraphabschnitt stehen.

fixed

M Im Abschnitt „Search tips“ ist in der Aufzählung vor dem letzten Punkt eine unnötige Leerzeile.

LATER TODO

C Im Satz mit „In GitHub, an issue can be closed as either“ ist die Formatierung von „completed“ misslungen.

configuration manual fix list

LATER TODO

https://qubes-doc-rst.readthedocs.io/en/latest/introduction/support.html

C Im Abschnitt „I have a problem or a question.“ ist in der Aufzählung im 5. Punkt das „qubes-users“ nicht in dicktengleicher Schrift.

LATER TODO

C Im Abschnitt „I didn’t find a solution or an answer!“ dito.

LATER TODO

C Im Abschnitt „Where’s the best place to discuss Qubes?“ dito.

LATER TODO

? Im Abschnitt „Social media“ fehlen die Links in der Aufzählung.
https://www.w3schools.com/TAGS/att_a_rel.asp

CODE TODO
or manual after conversion

M Im Abschnitt „Chat“ ist die Aufzählung kaputt.

fixed

https://qubes-doc-rst.readthedocs.io/en/latest/user/hardware/system-requirements.html

C Im ersten Warning-Block ist „necessary, but not sufficient“ nicht kursiv und der Link „resources below“ fehlt.

should be fixed in converison rst python repo, either in code or config

https://qubes-doc-rst.readthedocs.io/en/latest/user/hardware/certified-hardware.html

C Im ersten Danger-Block fehlen mehrere Kursiv-Formatierungen.

should be fixed in converison rst python repo, either in code or config

https://qubes-doc-rst.readthedocs.io/en/latest/user/downloading-installing-upgrading/installation-guide.html

C Im ersten und zweiten Danger-Block fehlt der Link „installation security“.

should be fixed in converison rst python repo, either in code or config

C Im ersten Warning-Block fehlt die Hervorhebung von „nested virtualization“.

should be fixed in converison rst python repo, either in code or config

C Im zweiten Warning-Block fehlen zwei Links.

should be fixed in converison rst python repo, either in code or config

C Im ersten Note-Block fehlt ein Link.

should be fixed in converison rst python repo, either in code or config

? Im Abschnitt „Installation summary“ ist der erste Note-Block blau statt grün.

LATER TODO

C Im Abschnitt „Installation destination“ fehlen im ersten Warning-Block Kursiv-Formatierungen.

should be fixed in converison rst python repo, either in code or config
or manual after conversion

C Im Abschnitt „Installation destination“ fehlen im ersten Note-Block ein Link und eine Formatierung.

should be fixed in converison rst python repo, either in code or config

https://qubes-doc-rst.readthedocs.io/en/latest/user/downloading-installing-upgrading/testing.html

C Der schwebende Caution-Block fehlt: „Caution: This page is intended for advanced users.“.

should be fixed in converison rst python repo, either in code or config
This comes from jekyll when generating the page. It should be manually added after conversion to all the dedicated pages with caution

? Im Abschnitt „Providing feedback“ fehlen die Symbole für „Daumen-hoch“ und „Daumen-runter“.

LATER TODO
https://stackoverflow.com/questions/1862472/symbols-in-restructuredtext

https://qubes-doc-rst.readthedocs.io/en/latest/user/how-to-guides/how-to-update.html

C Im Abschnitt „Security updates“ ist „qubes-secpack“ nicht dicktengleich formatiert.

LATER TODO

C Im ersten Note-Block fehlen zwei Links.

should be fixed in converison rst python repo, either in code or config

C Im Abschnitt „AEM resealing after updating“ ist „README“ nicht dicktengleich formatiert.

LATER TODO

C Im Abschnitt „Command-line interface“ sind im ersten Danger-Block Formatierungen falsch und ein Link fehlt.

should be fixed in converison rst python repo, either in code or config

https://qubes-doc-rst.readthedocs.io/en/latest/user/how-to-guides/backup-emergency-restore-v3.html

C In Punkten 3, 5, und 10 sind manche Notes im selben Paragraph statt in getrennten.

fixed

https://qubes-doc-rst.readthedocs.io/en/latest/user/how-to-guides/backup-emergency-restore-v4.html

C In Punkten 6 und 8 sind die Notes nicht abgesetzt.

thery are?

https://qubes-doc-rst.readthedocs.io/en/latest/user/how-to-guides/how-to-copy-from-dom0.html

? Im Titel „Copying from dom0“ ist „from“ nicht fett hervorgehoben.

LATER TODO

? Im Titel „Copying to dom0“ ist „to“ nicht fett hervorgehoben.

LATER TODO

https://qubes-doc-rst.readthedocs.io/en/latest/user/how-to-guides/how-to-install-software.html

C Im Satz „Make sure you restart your app qube after shutting down your template.“ ist „after“ nicht kursiv.

LATER TODO

C Im Satz „This command will roll back any changes made during the last time the template was run, but not before.“ ist „not“ nicht kursiv.

LATER TODO

M Im Abschnitt „Autostarting Installed Applications“ ist der Befehl „ls /usr/share/applications“ wegen zu vieler Leerzeichen schlecht formatiert.

AFTERCONVERSION TODO

https://qubes-doc-rst.readthedocs.io/en/latest/user/how-to-guides/how-to-use-disposables.html

C Im Abschnitt „Example of RPC policies to allow this behavior“ ist die Aufzählung schlecht formatiert.

fixed

https://qubes-doc-rst.readthedocs.io/en/latest/user/how-to-guides/how-to-use-devices.html

C Im Abschnitt „Introduction“ ist die Aufzählung schlecht formatiert.

fixed

https://qubes-doc-rst.readthedocs.io/en/latest/user/how-to-guides/how-to-use-block-storage-devices.html

C Im Abschnitt „Block Devices in VMs“ ist der Link „frontend-dev-option“ unzureichend formatiert.

actually it is ok

https://qubes-doc-rst.readthedocs.io/en/latest/user/how-to-guides/how-to-use-usb-devices.html

M „sys-usb:2-5 - 058f_USB_2.0_Camera“ ist schlecht formatiert.

fixed in config

C Der Link im Satz „Strip the address and pass it to the qvm-pci tool to attach the controller to the targetVM.“ ist unzureichend formatiert.

imho no action needed here

https://qubes-doc-rst.readthedocs.io/en/latest/user/how-to-guides/how-to-use-pci-devices.html

C Im Abschnitt „Attaching Devices Using the GUI“ ist Punkt 1.1 schlecht formatiert.

fixed in config

? Im Satz „The qvm-pci tool allows PCI attachment and detachment. It’s a shortcut for qvm-device pci“ ist „qvm-device pci“ nicht dicktengleich formatiert. Außerdem fehlt das Satzendezeichen.

CHECK TODO

https://qubes-doc-rst.readthedocs.io/en/latest/user/how-to-guides/how-to-reinstall-a-template.html

C Im Abschnitt „Manual Method“ fehlen in der Aufzählung Absätze.

fixed in markdown

https://qubes-doc-rst.readthedocs.io/en/latest/user/templates/minimal-templates.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.

should be fixed in converison rst python repo, either in code or config
This comes from jekyll when generating the page. It should be manually added after conversion to all the dedicated pages with caution

https://qubes-doc-rst.readthedocs.io/en/latest/user/templates/templates.html

? Tabelle: Links fehlen und Formatierungen auch.

STILL TODO

C Im Satz „Dom0 compromise is absolutely fatal, and it leads to Game OverTM.“ ist „TM“ nicht hochgestellt.

https://qubes-doc-rst.readthedocs.io/en/latest/user/templates/fedora/fedora-upgrade.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.

DONE TODO check after stage 2
This comes from jekyll when generating the page. It should be manually added after conversion to all the dedicated pages with caution

C Links fehlen im ersten Danger-Block.

https://qubes-doc-rst.readthedocs.io/en/latest/user/templates/debian/debian-upgrade.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.

should be fixed in converison rst python repo, either in code or config
This comes from jekyll when generating the page. It should be manually added after conversion to all the dedicated pages with caution

C Links fehlen im ersten Danger-Block.

CODE TODO

M Im Abschnitt „Debian 9 (“Stretch”)“ haben zwei dicktengleiche Teile überflüssige Leerzeichen.

LATER TODO

https://qubes-doc-rst.readthedocs.io/en/latest/user/templates/windows/windows-qubes-4-1.html

C Im Abschnitt „Windows VM installation“ ist die erste Aufzählung schlecht formatiert.

fixed in markdown

C Im Abschnitt „Create Windows VM“ ist die Aufzählung sehr schlecht formatiert.

fixed in markdown

? In der Aufzählung „These parameters are set for the following reasons:“ ist der Punkt 3 sehr schlecht formatiert (Codeblock).

fixed in markdown

? Im Abschnitt „Start Windows VM“ ist Punkt 1 der Aufzählung sehr schlecht formatiert (Codeblock).

fixed in markdown

M Im Abschnitt „Start Windows VM“ ist bei Punkt 2 der Aufzählung der Warning-Block schlecht formatiert (auch in der Markdown-Version!).

should be fixed in converison rst python repo, either in code or config
This comes from jekyll when generating the page. It should be manually added after conversion to all the dedicated pages with caution

M Im Punkt „On systems shipped with a Windows license, the product key may be read from flash via root in dom0:“ ist der nachfolgende Befehl nicht in einem abgesetzten Codeblock (ähnlich auch in der Markdown-Version).

fixed in markdown

? Im Abschnitt „After Windows installation“ ist der Codeblock falsch formatiert.

fixed in markdown

C Der Satz „At this point you may open a tab in dom0 for debugging, in case something goes amiss:“ ist nicht abgesetzt.

fixed in markdown

C Im Abschnitt „Windows as a template“ sind zwei Codeblöcke falsch formatiert.

https://qubes-doc-rst.readthedocs.io/en/latest/user/templates/windows/qubes-windows-tools-4-1.html

C? In der ersten Tabelle fehlen die Plusse und Minusse.

exchanged with y and n for + and - in markdown, weird formatting when using + it is formatted as a bullet list

C Die Aufzählung unter der ersten Tabelle ist schlecht formatiert.

fixed in markdown

M Der Satz „(where <VMname> is the name of your Windows VM)“ ist schlecht formatiert. Achtung, dieser Fehler taucht mehrmals auf!

LATER TODO, deleted the mardown formatting though

C Der Satz „You can also install the package from testing repositories, where we usually publish new versions first:“ ist nicht abgesetzt.

actually it is ok

? Der Satz „Several times, Windows security may ask for confirmation of driver installation.“ startet neben dem Bild statt darunter.

fixed in markdown

C Im Abschnitt „Xen PV drivers and Qubes Windows Tools“ ist die Aufzählung schlecht formatiert.

fixed in markdown

M Der Satz „where <VMname> is the name of your windows qube“ ist schlecht formatiert. Achtung, dieser Fehler taucht mehrmals auf!

LATER TODO, deleted the mardown formatting though

M Der Teilsatz „via the Open/Edit in DisposableVM command“ ist schlecht formatiert.

LATER TODO, deleted the mardown formatting though, see https://stackoverflow.com/questions/11984652/bold-italic-in-restructuredtext

? Im Abschnitt „Configuration“ fehlen in der ersten Tabelle die Backslashes im Pfad.

LATER TODO

? Im Abschnitt „Configuration“ ist die zweite Tabelle schlecht formatiert und enthält Fehlermeldungen.

LATER TODO

? Im Abschnitt „Troubleshooting“ ist in der ersten Tabelle der Pfad „C:\move-profiles.log“ schlecht formatiert und ohne Backslashes.

LATER TODO

https://qubes-doc-rst.readthedocs.io/en/latest/user/templates/windows/migrate-to-4-1.html

C Im Abschnitt „Preparation for Windows 10 and 11“ ist die Aufzählung kaputt.

fixed in markdown

https://qubes-doc-rst.readthedocs.io/en/latest/user/troubleshooting/installation-troubleshooting.html

? Im Abschnitt „“Not asking for VNC because we don’t have a network” / “X startup failed, aborting installation” / “Pane is dead” error during installation“ sind die Codeblöcke kaputt.
-fixed in markdown

https://qubes-doc-rst.readthedocs.io/en/latest/user/security-in-qubes/firewall.html

? Im Satz „For details of that usage see here“ führt der Link zu readthedocs, aber 404. Wurde die verlinkte Seite nicht gerendert?

M Im Satz „Opening a single TCP port to other network-isolated qube“ ist eine Note falsch formatiert.

LATER TODO

https://qubes-doc-rst.readthedocs.io/en/latest/user/security-in-qubes/data-leaks.html

C Im Abschnitt „Types of Data Leaks“ ist der Satz (und folgende) nicht abgesetzt: „Both Qubes firewall and an empty NetVM …“

fixed in markdown

https://qubes-doc-rst.readthedocs.io/en/latest/user/security-in-qubes/vm-sudo.html

? Der Satz „| Passwordless root is provided by the qubes-core-agent-passwordless-root package. |“ hat die Pipes zuviel.

locally rendering i do not see them, so LATER TODO

maiska · 2024-08-11T14:50:35Z

I'm done. Other issues I've found:

https://qubes-doc-rst.readthedocs.io/en/latest/user/security-in-qubes/split-gpg.html

C Im Abschnitt „Thunderbird 78 and higher“ ist der erste Absatz schlecht formatiert.

removed high lighting , LATER TODO

C? Im Abschnitt „Setup Description“ fehlen in der Tabelle die Formatierungen.

think it is ok

C Unter dieser Tabelle fehlen in der Aufzählung Absätze.

fixed in markdown, though locally rendered right

https://qubes-doc-rst.readthedocs.io/en/latest/user/security-in-qubes/mfa.html

C Im Abschnitt „Setup login with YubiKey / NitroKey3“ fehlen viele Absätze in der Aufzählung „Install YubiKey / NitroKey3 software in the template on which your USB VM is based.“.

fixed in markdown

M? Im Abschnitt „Optional: Locking the screen when YubiKey / NitroKey3 is removed“ ist die Nummerierung durcheinander.

fixed in markdown

https://qubes-doc-rst.readthedocs.io/en/latest/user/advanced-topics/how-to-install-software-in-dom0.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.

should be fixed in converison rst python repo, either in code or config
This comes from jekyll when generating the page. It should be manually added after conversion to all the dedicated pages with caution

https://qubes-doc-rst.readthedocs.io/en/latest/user/advanced-topics/volume-backup-revert.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.

should be fixed in converison rst python repo, either in code or config
This comes from jekyll when generating the page. It should be manually added after conversion to all the dedicated pages with caution

https://qubes-doc-rst.readthedocs.io/en/latest/user/advanced-topics/standalones-and-hvms.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.

should be fixed in converison rst python repo, either in code or config
This comes from jekyll when generating the page. It should be manually added after conversion to all the dedicated pages with caution

C Im Abschnitt „Creating a standalone“ ist die Aufzählung kaputt.

fixed in markdown

https://qubes-doc-rst.readthedocs.io/en/latest/user/advanced-topics/config-files.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.

should be fixed in converison rst python repo, either in code or config
This comes from jekyll when generating the page. It should be manually added after conversion to all the dedicated pages with caution

? Im Abschnitt „GUI and audio configuration in dom0“ fehlt im ersten Punkt der Liste ein Absatz.

https://qubes-doc-rst.readthedocs.io/en/latest/user/advanced-topics/secondary-storage.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.

should be fixed in converison rst python repo, either in code or config
This comes from jekyll when generating the page. It should be manually added after conversion to all the dedicated pages with caution

https://qubes-doc-rst.readthedocs.io/en/latest/user/advanced-topics/rpc-policy.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.

DONE TODO check after stage 2
This comes from jekyll when generating the page. It should be manually added after conversion to all the dedicated pages with caution

https://qubes-doc-rst.readthedocs.io/en/latest/user/advanced-topics/usb-qubes.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.

should be fixed in converison rst python repo, either in code or config
This comes from jekyll when generating the page. It should be manually added after conversion to all the dedicated pages with caution

https://qubes-doc-rst.readthedocs.io/en/latest/user/advanced-topics/managing-vm-kernels.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.

should be fixed in converison rst python repo, either in code or config
This comes from jekyll when generating the page. It should be manually added after conversion to all the dedicated pages with caution

? Im Abschnitt „Installing different VM kernel based on dom0 kernel“ ist die Liste nach/in dem ersten Absatz kaputt.

https://qubes-doc-rst.readthedocs.io/en/latest/user/advanced-topics/salt.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.

should be fixed in converison rst python repo, either in code or config
This comes from jekyll when generating the page. It should be manually added after conversion to all the dedicated pages with caution

C Im Abschnitt „Debugging“ ist die Aufzählung falsch formatiert.

fixed in markdown

https://qubes-doc-rst.readthedocs.io/en/latest/user/advanced-topics/gui-domain.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.

should be fixed in converison rst python repo, either in code or config
This comes from jekyll when generating the page. It should be manually added after conversion to all the dedicated pages with caution

https://qubes-doc-rst.readthedocs.io/en/latest/user/advanced-topics/disposable-customization.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.

should be fixed in converison rst python repo, either in code or config
This comes from jekyll when generating the page. It should be manually added after conversion to all the dedicated pages with caution

https://qubes-doc-rst.readthedocs.io/en/latest/user/advanced-topics/installing-contributed-packages.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.

should be fixed in converison rst python repo, either in code or config
This comes from jekyll when generating the page. It should be manually added after conversion to all the dedicated pages with caution

https://qubes-doc-rst.readthedocs.io/en/latest/user/advanced-topics/bind-dirs.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.

should be fixed in converison rst python repo, either in code or config
This comes from jekyll when generating the page. It should be manually added after conversion to all the dedicated pages with caution

? Im Abschnitt „What is it useful for?“ ist „/var/lib/tor“ nicht dicktengleich formatiert.

changed the way the url ist being linked

M? Im Abschnitt „Limitations“ fehlt im letzten Punkt beim Link „rw/config/rc.local“ ein vorangestelltes Slash. Außerdem muss dann „/rw/config/rc.local“ dicktengleich formatiert werden.

CODE TODO - in phase 2 an configuration

https://qubes-doc-rst.readthedocs.io/en/latest/user/advanced-topics/gui-configuration.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.

should be fixed in converison rst python repo, either in code or config
This comes from jekyll when generating the page. It should be manually added after conversion to all the dedicated pages with caution

https://qubes-doc-rst.readthedocs.io/en/latest/user/advanced-topics/resize-disk-image.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.

should be fixed in converison rst python repo, either in code or config
This comes from jekyll when generating the page. It should be manually added after conversion to all the dedicated pages with caution

https://qubes-doc-rst.readthedocs.io/en/latest/user/advanced-topics/qubes-service.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.

should be fixed in converison rst python repo, either in code or config
This comes from jekyll when generating the page. It should be manually added after conversion to all the dedicated pages with caution

https://qubes-doc-rst.readthedocs.io/en/latest/user/advanced-topics/mount-from-other-os.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.

should be fixed in converison rst python repo, either in code or config
This comes from jekyll when generating the page. It should be manually added after conversion to all the dedicated pages with caution

C Im Abschnitt „How to mount a Qubes partition from another OS“ ist die Liste kaputt.

fixed in markdown

CR? In der Tabelle ist in der ersten Spalte die Zelle mit „ot her_install/-private“ kaputt: Das Leerzeichen ist dort zuviel!

https://qubes-doc-rst.readthedocs.io/en/latest/user/advanced-topics/kde.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.

should be fixed in converison rst python repo, either in code or config
This comes from jekyll when generating the page. It should be manually added after conversion to all the dedicated pages with caution

https://qubes-doc-rst.readthedocs.io/en/latest/user/advanced-topics/i3.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.

should be fixed in converison rst python repo, either in code or config
This comes from jekyll when generating the page. It should be manually added after conversion to all the dedicated pages with caution

https://qubes-doc-rst.readthedocs.io/en/latest/user/advanced-topics/awesomewm.html

C Schwebender Block „Caution: This page is intended for advanced users.“ fehlt.

should be fixed in converison rst python repo, either in code or config
This comes from jekyll when generating the page. It should be manually added after conversion to all the dedicated pages with caution

https://qubes-doc-rst.readthedocs.io/en/latest/developer/general/gsoc.html

M Im Abschnitt „Secure Boot support“ sind zwei Aufzählungen kaputt.

fixed in markdown

M Im Abschnitt „Reduce logging of Disposable VMs“ ist eine Aufzählung kaputt.

fixed in markdown

https://qubes-doc-rst.readthedocs.io/en/latest/

? Der Link „How to edit the documentation“ führt zu qubes-os.org, nicht RtD. Soll das so sein?

? Der Link „Documentation style guide“ führt zu qubes-os.org, nicht RtD. Soll das so sein?

? Der Link „Website style guide“ führt zu qubes-os.org, nicht RtD. Soll das so sein?

? Der Link „Visual style guide“ führt zu qubes-os.org, nicht RtD. Soll das so sein?

yep that is correct, it should be that way

https://qubes-doc-rst.readthedocs.io/en/latest/developer/general/usability-ux.html

M Die „Important“-Blöcke sollen eigentlich keine Blöcke sein.

why not? :) nice to have after conversion to look at, LATER TODO

M Unter „Minimize Repetitive Steps“ ist die Aufzählung „Navigate through file system“ nicht untergeordnet.

u mean there is no tab -> nice to have, LATER TODO

https://qubes-doc-rst.readthedocs.io/en/latest/developer/code/source-code.html

C Der Absatz „Opening a pull request on GitHub …“ ist nicht abgesetzt.

fixed in markdown

https://qubes-doc-rst.readthedocs.io/en/latest/developer/code/code-signing.html

M Im Abschnitt „Code Signature Checks“ sind die beiden Zitate in der Aufzählung falsch formatiert. Besser wäre es, sie in Backticks zu setzen, oder? Dann sollte es aber bei den anderen Zitaten auch gemacht werden.

fixed in markdown, otherwise bc of quoting - nice to have + LATER TODO

https://qubes-doc-rst.readthedocs.io/en/latest/developer/services/qrexec2.html

? Der Titel „Qubes RPC internals“ ist zu klein geschrieben. Zu untersuchen.

fixed in markdown

https://qubes-doc-rst.readthedocs.io/en/latest/developer/services/qrexec-internals.html

C Es fehlen in den Listen die Absätze!

i don't see it

https://qubes-doc-rst.readthedocs.io/en/latest/developer/services/qrexec-socket-services.html

M Im Abschnitt „Example: qrexec-policy-agent“ ist die Liste falsch formatiert.

https://qubes-doc-rst.readthedocs.io/en/latest/developer/services/admin-api.html

C Im ersten Satz „You may also be interested in the article …“ fehlt nach „article“ ein Leerzeichen. Außerdem ist der Link nicht kursiv.

LATER TODO for italic link

https://qubes-doc-rst.readthedocs.io/en/latest/developer/services/admin-api.html

? Im Abschnitt „The calls“ sind in der Tabelle manche Formatierungen verloren gegangen.

LATER TODO

https://qubes-doc-rst.readthedocs.io/en/latest/developer/debugging/automated-tests.html

M Im Abschnitt „Looking for patterns in tests“ sind die Listen kaputt.

fixed in markdown

https://qubes-doc-rst.readthedocs.io/en/latest/developer/debugging/vm-interface.html

M Im Abschnitt „Qubes RPC“ ist die Liste unter „Caller sends name of requested icon. This can be one of:“ nicht ausreichend eingerückt.

LATER TODO

https://qubes-doc-rst.readthedocs.io/en/latest/developer/building/qubes-builder.html

C Im „Warning“-Block fehlen ein Absatz und ein Link.

I do not see a missing paragraph here, but the link shluld eithere be fixed using code, config or manually after the conversion TODO

M Im Abschnitt „Manual source modification“ ist in der Liste der Punkt „You can also set GIT_PREFIX=“marmarek/qubes-” to use marmarek’s repo“ nicht ausreichend eingerückt.

LATER TODO

https://qubes-doc-rst.readthedocs.io/en/latest/developer/building/qubes-builder-details.html

C Im „Warning“-Block fehlen ein Absatz und ein Link.

I do not see a missing paragraph here, but the link shluld eithere be fixed using code, config or manually after the conversion TODO

https://qubes-doc-rst.readthedocs.io/en/latest/developer/building/qubes-iso-building.html

C Im „Warning“-Block fehlen ein Absatz und ein Link.

I do not see a missing paragraph here, but the link shluld eithere be fixed using code, config or manually after the conversion TODO

https://qubes-doc-rst.readthedocs.io/en/latest/developer/releases/version-scheme.html

C Im Abschnitt „Release schedule“ fehlt in der Tabelle eine Formatierung.

LATER TODO

EDIT: checkboxes added

maiska · 2024-08-11T14:51:25Z

I missed some files. This should be the rest:

https://qubes-doc-rst.readthedocs.io/en/latest/user/downloading-installing-upgrading/installation-guide-4.1.html

C In allen Blöcken fehlen Formatierungen und/oder Links.

should be fixed in converison rst python repo, either in code or config

https://qubes-doc-rst.readthedocs.io/en/latest/user/security-in-qubes/firewall_4.1.html

M Im Abschnitt „Opening a single TCP port to other network-isolated qube“ ist in der Aufzählung eine Note falsch formatiert.

M Im Abschnitt „Port forwarding to a qube from the outside world“ sind in der Aufzählung fünf Noten falsch formatiert.

LATER TODO

https://qubes-doc-rst.readthedocs.io/en/latest/user/templates/windows/qubes-windows-tools-4-0.html

R Im Abschnitt „Configuration“ fehlen in der ersten Tabelle die Backslashes.

C? Im Abschnitt „Configuration“ ist die zweite Tabelle schlecht formatiert.

LATER TODO

https://qubes-doc-rst.readthedocs.io/en/latest/user/templates/windows/windows-qubes-4-0.html

M Im Abschnitt „Simple Windows install“ ist die Aufzählung schlecht formatiert.

M Im Abschnitt „Windows as a template“ sind zwei Codeblöcke schlecht formatiert.

fixed in markdown

maiska · 2024-08-11T14:57:24Z

Hello all,

all the markdown changes in qubes-doc that relate somewhat to the rst conversion are in this pull request:
#1418

I updated config, some code to fix different minor errors in the repo: https://github.com/maiska/qubes-translation-utilz

Ran the script on the current qubes-doc main state and the result is here: https://github.com/maiska/qubes-doc.rtd/tree/rtd-deploy-test and deployed here: https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-test/

Also ran the script on the incorporated changes to be seen in the PR from above and the result is here: https://github.com/maiska/qubes-doc.rtd/tree/rtd-deploy-pr and deployed here: https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/

If you have the time @tokideveloper please feel free to go over the deployed version before @marmarek could run it on his rst2 branch and deploy.

@unman If you find some time perhaps you could go over the pull request: #1418 ? . I tested locally, meaning jekyll build was ok, but did not spend time looking for errors, just that is up and looks good.

tokideveloper · 2024-08-17T18:42:30Z

Ran the script on the current qubes-doc main state and the result is here: https://github.com/maiska/qubes-doc.rtd/tree/rtd-deploy-test and deployed here: https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-test/

Also ran the script on the incorporated changes to be seen in the PR from above and the result is here: https://github.com/maiska/qubes-doc.rtd/tree/rtd-deploy-pr and deployed here: https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/

If you have the time @tokideveloper please feel free to go over the deployed version before @marmarek could run it on his rst2 branch and deploy.

Thank you for your work, @maiska!

I'm not sure which Markdown version to compare with which RST version since you put links to two deployed versions (in sum after an edit) in your post. So, which deployed version do you mean (link)?

So, just by guessing, I started to compare https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/ with https://www.qubes-os.org/doc/ since it seems to be the newest version (incorporated Markdown stuff). But I found that the pictures are missing (see the introduction and screenshots pages). @maiska, could you please deploy a pictured version? That would be great! Meanwhile, I'll continue comparing. Please stop me if I'm comparing the wrong RST version. ;-)

Thanks!

tokideveloper · 2024-08-19T00:06:24Z

@maiska

Now, I compared the docs on https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/ with the docs on https://www.qubes-os.org/doc/ and this is the result. For the sake of simplicity, I'll write all issues down that I found.

In general, section titles (like "Introduction" and "User Documentation") are missing on the TOC on the left side. See here for a better example: https://qubes-doc-rst.readthedocs.io/en/latest/index.html

Now the pages:

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/

The section titles "Introduction", "User documentation", "Project security", "Developer documentation" and "External documentation" should be larger than their subsection titles but smaller than "Table of contents".

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/introduction/intro.html

The note below the first picture is not in a box.
The note in section "Features" should be in a box and not indented.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/introduction/getting-started.html

The first link ("downloading") is broken.
In subsection "Command-line interface", "Alt + F3" is broken.
Several links in the sections "Compatible Hardware", "Downloads" and "Documentation" are broken.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/introduction/faq.html

In section "How does Qubes OS compare to using a separate physical machine?", the "Pros" and "Cons" list titles are put in "Important" boxes. That's too much in my view. Simple texts in bold font would be sufficient IMHO.
In section "What about safe languages and formally verified microkernels?", the link is missing.
In section "Why does Qubes use Xen instead of KVM or some other hypervisor?", the link is missing.
In section "How should I report documentation issues?", the first link is broken.
In section "Should I trust this website?", the link "intentionally written in Markdown so as to be readable as plain text for this very reason" is plain text.
In section "Is there a list of hardware that is compatible with Qubes OS?", the link is broken.
In section "How do I access my external drive?", the link "sys-usb" is not monospaced (maybe impossible to mix link and monospace font; if so then keep the link and drop monospacing IMHO).

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/introduction/issue-tracking.html

In section "I see something that should be changed in the documentation.", the link is broken.
In section "Meta-issues", the "Rationale" paragraphs shall have a new line before each. I can see that a new lines has been added here but that's not working. Maybe it's not working at all. Then it's okay to have no new lines before them.
In section "Search tips", third item, the links are badly formatted. In general, for monospaced links, see here.
In section "Resolution", the first link is broken.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/introduction/support.html

In section "I have a problem or a question.", item number 5, "qubes-users" is not monospaced.
Dito in the subsequent section "I didn’t find a solution or an answer!".
Dito in section "Where’s the best place to discuss Qubes?".
In section "Staying safe", in the last paragraph, the first two links are broken.
In section "Report issues and submit changes in the right places", the last link is broken.
In section "qubes-users", four links are broken (see the lists there).
In section "Social media", the links in the list are not linking.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/introduction/contributing.html

In section "How to contribute", several links are broken.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/hardware/system-requirements.html

In section "Choosing Hardware", third item, the link is broken.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/hardware/certified-hardware.html

In section "Certified hardware", two links are broken.
In section "Hardware certification process", the first link is broken.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/hardware/how-to-use-the-hcl.html

In section "How to use the hardware compatibility list (HCL)", the first link is broken.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/downloading-installing-upgrading/installation-guide.html

In section "Hardware requirements", a link to the HCL is broken.
In section "Copying the ISO onto the installation medium", the two "Download" links are broken.
In section "Installation summary", the first box should be green, not blue.
The title of the section "Installation destination" is broken. Reads "### Installation destination". Maybe a newline is missing above the title section in the Markdown version.
In section "Localization", the box "Did you know?" should be green, not blue.
In the same box, "/boot" is not monospaced.
In section "Getting help", first item, the second link is broken.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/downloading-installing-upgrading/upgrade/3_1.html

In section "Upgrading dom0", fourth item, a newline is missing after the first sentence. Maybe it's not feasible. Then, it's okay as it is now.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/downloading-installing-upgrading/upgrade/4_0.html

In section "Preparation", first item, the link is broken.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/downloading-installing-upgrading/upgrade/4_1.html

In section "Clean installation", item number 2, the link is broken.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/downloading-installing-upgrading/upgrade/4_2.html

In section "Clean installation", item number 5, the link is broken.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/downloading-installing-upgrading/supported-releases.html

In section "Qubes OS", the "Downloads" link is broken.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/downloading-installing-upgrading/testing.html

In section "Releases", first item, the first link is broken.
In section "Providing feedback", the icons for "thumbs up" and "thumbs down" are missing.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/how-to-guides/how-to-organize-your-qubes.html

In section "Conclusion", second item, the link is not in bold font. If it's not possible to do so, let it be as it is.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/how-to-guides/how-to-update.html

In section "How to update", first paragraph, the links are not in italic font. If it's not possible to do so, let it be as it is.
In section "Security updates", "qubes-secpack" is not in monospaced font.
In section "Command-line interface", first red box, several command names are not in monospaced font.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/how-to-guides/how-to-back-up-restore-and-migrate.html

In section "Creating a backup", the list items have lost their paragraphs. If it's not possible to do so, let it be as it is.
Dito in section "Restoring from a backup", item number 4.
In section "Migrating between two physical machines", the link is broken.
In section "Choosing a backup passphrase", the items are badly formatted.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/how-to-guides/how-to-copy-and-move-files.html

In section "How to copy and move files", first paragraph, the links are not in italic font. If it's not possible to do so, let it be as it is.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/how-to-guides/how-to-copy-from-dom0.html

The title of the section "Copying from dom0" misses an emphasis of "from".
The title of the section "Copying to dom0" misses an emphasis of "to".

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/how-to-guides/how-to-install-software.html

In section "Installing Snap Packages", item number 3, a newline is missing.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/how-to-guides/how-to-use-block-storage-devices.html

In section "How to use block storage devices", first paragraph, the link is not in italic font.
In section "Command Line Tool Guide", item number 2 and 4 lack a newline. If it's not possible to do so, let it be as it is.
In section "Attaching a File", item number 2 misses some newlines.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/how-to-guides/how-to-use-usb-devices.html

In section "How to use USB devices", first paragraph, the link is not in italic font.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/how-to-guides/how-to-use-pci-devices.html

In section "How to use PCI devices", first paragraph, the link is not in italic font. If it's not possible to do so, let it be as it is.
In section "qvm-pci Usage", first paragraph, the link is not in monospaced font. If it's not possible to do so, let it be as it is.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/how-to-guides/how-to-reinstall-a-template.html

In section "Manual Method", item numbers 1 and 2, newlines are missing. If it's not possible to do so, let it be as it is.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/templates/templates.html

In section "Installing", the paragraphs between the code blocks are badly formatted.
In section "Inheritance and persistence", the table has several issues:
- The footnotes (reference and referee) are not in superscript.
- "template" is written "t emplate".
- The links in the first column are missing
- /etc/skel and others are not in monospaced font.
In section "Important Notes", first item, the "Disk Trim" link is missing.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/templates/fedora/fedora-upgrade.html

In section "Detailed instructions for standard Fedora templates", item number 3, the second "Note:" is not in a separate paragraph.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/templates/debian/debian-upgrade.html

In section "How to upgrade a Debian template in-place", the red box lacks its two links inside.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/templates/minimal-templates.html

In section "Important", item number 2, the second link is broken.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/troubleshooting/update-troubleshooting.html

In section "Dom0 and/or template update stalls when updating via the GUI tool", the list is broken. A newline in front of it in the Markdown version could help.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/troubleshooting/uefi-troubleshooting.html

In section "Successfully installed in legacy mode, but had to change some kernel parameters", the second list is broken. Probably to be fixed in the Markdown version.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/troubleshooting/resume-suspend-troubleshooting.html

In section "Suspend/resume troubleshooting", the link is broken.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/security-in-qubes/firewall.html

In section "Opening a single TCP port to other network-isolated qube" -> "1. Simple port binding", the second item, a note is broken. Probably to be fixed in the Markdown version.
In section "Port forwarding to a qube from the outside world"
- -> "2. Route packets from the outside world to the FirewallVM", several notes are broken. Probably to be fixed in the Markdown version.
- -> "3. Route packets from the FirewallVM to the VM", several notes are broken. Probably to be fixed in the Markdown version.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/security-in-qubes/data-leaks.html

In section "Types of Data Leaks", item number 3, a newline is missing in front of "Both Qubes firewall …".

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/security-in-qubes/vm-sudo.html

In section "Passwordless root access in qubes", the text below the code block is broken.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/security-in-qubes/split-gpg.html

In section "Thunderbird 78 and higher", first paragraph, work-email and work-gpg are not in bold font. If it's not possible to do so, let it be as it is.
In section "Setup Description",
- the table, the entries shall be formatted in monospaced font.
- below the table, the lists lack newlines.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/security-in-qubes/mfa.html

In general, keystrokes combinations like "ctrl+alt+F2" are highlighted in a special way on the related original doc page while this is missing in the RTD version. Could be "corrected" in the Markdown file by replacing with ctrl+alt+F2 and so on.

In section "Setup login with YubiKey / NitroKey3", the enumerated lists lack newlines. A workaround could be to make nested lists like

1. Install YubiKey / NitroKey3 software in the template …
   - YubiKey
     - For Fedora.
       (codeblock)
     - For Debian.
       (codeblock)
   - NitroKey3
     - Follow the installation instructions …
     - WARNING: as of April 2024 the official instructions involve …

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/advanced-topics/managing-vm-kernels.html

In section "Installing different VM kernel based on dom0 kernel", the first list is broken.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/advanced-topics/bind-dirs.html

In section "What is it useful for?", second paragraph, the link text ("has been made persistent") is only the middle of the original link text ("Tor’s data dir /var/lib/tor has been made persistent in the TemplateBased ProxyVM sys-whonix").
In section "Limitations", last item, the link "rw/config/rc.local" is not in bold font.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/advanced-topics/resize-disk-image.html

In section "Decreasing the size of Disk Images", last paragraph, the link is missing.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/project-security/verifying-signatures.html

In section "How to verify the cryptographic hash values of Qubes ISOs", the two "downloads" links are broken.
Dito one time in section "How to verify detached PGP signatures on Qubes ISOs".
In section "Why am I getting “WARNING: This key is not certified with a trusted signature! There is no indication that the signature belongs to the owner.”?", the list is broken. Could probably be fixed in the Markdown version by adding a newline in front of it.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/developer/general/package-contributions.html

In section "Package contributions", first paragraph, the link is not in italic font.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/developer/general/usability-ux.html

In section "Usability & UX", second paragraph, the link is broken.
In General, the Dos and Don'ts titles are put in "Important" boxes. That's too much in my view. Simple texts in bold font would be sufficient IMHO.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/developer/system/architecture.html

In section "Key architecture features", the link "Architecture Spec v0.3 [PDF]" is missing.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/developer/system/gui.html

In section "qubes-gui and qubes-guid processes", first list, dummyqsb_drv and qubes_drv are badly formatted. To be fixed in the Markdown version.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/developer/services/dom0-secure-updates.html

In section "Secure update mechanism we use in Qubes (starting from Beta 2)", third paragraph, /var/lib/qubes/dom0-updates and –installroot= are badly formatted (crossed out) in the Markdown version. To be fixed in the Markdown version.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/developer/services/qrexec.html

In section "Policy files", the last list is broken. To be fixed in the Markdown version.
In section "Service policies with arguments", there is a visible HTML comment at the bottom which is not visible in the original version. The comment should be either removed or printed as normal text (in italic font IMHO).

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/developer/services/qrexec-internals.html

In section "Qrexec: Qubes RPC internals",
- the first two links are not in italic font.
- qrexec-agent is badly formatted. Probably to be fixed in the Markdown version.
In section "domX: request execution of service admin.Service in dom0", the lists lack inner paragraphs. A good workaround here could be to put those paragraphs into sublists in the Markdown version.
Dito in section "domX: invoke execution of qubes service qubes.Service in domY".

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/developer/services/admin-api.html

In section "Policy admin API", policy.Replace and policy.Remove are broken.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/developer/debugging/windows-debugging.html

In section "Modifying the NIC of the target VM", the Jekyll tag filters {% raw %} and {% endraw %} appear in the RST version where they shouldn't. To be removed during or after conversion to RST.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/developer/building/qubes-builder.html

In section "Manual source modification", make help should read make help (only one space character inbetween). To be fixed in the Markdown version.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/developer/releases/1_0/release-notes.html

In section "Downloads", the "Qubes Downloads" link is broken.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/developer/releases/2_0/release-notes.html

In section "Downloads", the "Qubes Downloads" link is broken.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/developer/releases/3_0/release-notes.html

In section "Downloads", the "Qubes Downloads" link is broken.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/developer/releases/3_1/release-notes.html

In section "Downloads", the "Qubes Downloads" link is broken.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/developer/releases/3_2/release-notes.html

In section "Downloads", the "Qubes Downloads" link is broken.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/developer/releases/4_0/release-notes.html

In section "Downloads", the "Qubes Downloads" link is broken.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/developer/releases/4_1/release-notes.html

In section "Downloads", the "Qubes Downloads" link is broken.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/developer/releases/4_2/release-notes.html

In section "Notes", the second item lacks newlines.
In section "Downloads", the "downloads" link is broken.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/developer/releases/version-scheme.html

In section "Release schedule", first table, current-testing is not in a monospaced font.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/downloading-installing-upgrading/installation-guide-4.1.html

In section "Hardware requirements",
- the "Hardware Compatibility List" link is broken.
- the yellow box, "nested virtualization" is not in bold font.
In section "Copying the ISO onto the installation medium", the "Download" and "downloads" links are broken.
In section "Installation summary", the first box is blue, not green.
In section "Installation destination",
- the first yellow box, "from" and "onto" are not in italic font.
- the third box is blue, not green; also, /boot is not in a monospaced font.
In section "Getting help", first item, the "improving" link is broken.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/security-in-qubes/firewall_4.1.html

In section "Opening a single TCP port to other network-isolated qube" -> "Simple port binding", the note is broken.
In section "Port forwarding to a qube from the outside world",
- -> "1. Identify the IP addresses you will need to use for sys-net, sys-firewall and the destination qube.", the note is inlined. To be fixed in the Markdown version by adding a newline in front of it.
- -> "2. Route packets from the outside world to the FirewallVM",
  - the paragraph starting with "If you want to expose the service …" is broken. To be fixed in the Markdown version.
  - the paragraph "Note: On Qubes R4, you can also check the nft counters" is broken. To be fixed in the Markdown version.
  - the paragraph "Note: Again in R4 the following needs to be added:" is broken. To be fixed in the Markdown version.
In section "Port forwarding to a qube from the outside world", -> "3. Route packets from the FirewallVM to the VM", two notes are broken.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/how-to-guides/backup-emergency-restore-v2.html

In section "Emergency backup recovery (v2)", openssl list-cipher-algorithms should read openssl list-cipher-algorithms.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/how-to-guides/backup-emergency-restore-v3.html

In section "Emergency backup recovery (v3)", item number 5, a newline is missing between the two notes. Alternatively, list the notes in the Markdown version.
Similarly in section "Emergency backup recovery (v3)", item number 10.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/how-to-guides/backup-emergency-restore-v4.html

In section "Emergency Recovery Instructions", item number 6, a newline is missing in front of the note. To be fixed in the Markdown version.
Dito in section "Emergency Recovery Instructions", item number 8.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/templates/windows/qubes-windows-tools-4-0.html

In section "Qubes Windows Tools (QWT) in Qubes OS 4.0", first paragraph, the link is not in italic font. If it's not possible to do so, let it be as it is.
In section "Installing Qubes guest tools in Windows 10 VMs",
- item numbers 1 and 6, normal text is formatted in monospaced font. To be fixed in the Markdown version.
- item number 6, a newline is needed in front of the note. To be fixed in the Markdown version by listing the note.
- item numbers 9 and 12, <VMname> is badly formatted. Probably to be fixed in the Markdown version.
- item number 12, the qvm-prefs command is not in its own paragraph. Probably to be fixed in the Markdown version by listing the command.
In section "Configuration",
- first table, the backslashes are missing.
- third table, the words "Component", "Setting" and "DisableCursor" have superfluous space characters.
In section "Troubleshooting",
- "/var/log/xen/console/guest-*" should be put into backticks since the asterisk renders to a non-existing footnote.
- first table, many words have superfluous space characters.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/templates/windows/qubes-windows-tools-4-1.html

In section "Installing Qubes Windows Tools (QWT) in a Windows VM",
- item number 1, a newline is needed in front of "You can also install the package …".
- item number 9, "If Windows is used in a …" should be in a separate paragraph.
- item number 10, the command should be in a separate paragraph.
In section "Configuration",
- first table,
  - first column, last line, "LogRetention" has a superfluous space character in it.
  - the backslashes are missing.
- third table, there are several superfluous space characters.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/templates/windows/windows-qubes-4-0.html

In section "How to install Windows qubes in Qubes OS 4.0", the link is not in italic font.
In section "Simple Windows install", item "Windows Installer:", third item, newlines are missing.

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/templates/windows/windows-qubes-4-1.html

In section "Windows VM installation"
- -> "Create Windows VM",
  - a newline has to be added after "Using Qube Manager".
  - "/var/log/xen/console/hypervisor.log: …" should be in a codeblock that is surrounded by newlines.
- -> "Start Windows VM"
  - -> item "Install Windows on the new VM", below the warning, the items are formatted as a codeblock.
  - -> the last two items, newlines are needed here. Probably to be fixed in the Markdown version.
- -> "After Windows installation" -> the last item, newlines are needed here. Probably to be fixed in the Markdown version.

The yellow top warning box "Caution: This page is intended for advanced users." is missing on the following pages:

maiska · 2024-08-19T05:16:40Z

@tokideveloper Thank you very much for your work.
The thing with the attachments is, that i added it as a submodule to the doc rst repo, readthedocs.yml is configured appropriately to checkout all of the repo submodules, but it still does not find them.
I havent got the time to debug the issue, because the options of the cofnigurations are being applied ...
Thnak you for your work, will see to fix the issues in a timely matter :)

tokideveloper · 2024-08-24T06:54:32Z

As mentioned above, there is a workaround for the missing newlines/paragraphs breaks.

The problem is that Markdown code like this:

1. Item one
    A
  
    B
  
    C

renders to this using Jekyll:

Item one
A

B

C

while ReStructuredText code like this:

1. Item one
    A
  
    B
  
    C

renders to this using Sphinx:

Item one
A B C

So, newlines / paragraph breaks are dropped in lists.

My suggested solution is to itemize those paragraphs. So, I would transform the Markdown code to

1. Item one
    - A
    - B
    - C

which renders to

Item one
- A
- B
- C

using Jekyll and also using Sphinx.

@maiska, if you give me your "Go!", I can apply this proposed solution to all Markdown files on branch qubes-doc:main.

But beforehand, I'd like to see PR #1418 merged. @maiska, @unman, are there any reasons for not merging that PR?

unman · 2024-08-24T11:55:49Z

On Fri, Aug 23, 2024 at 11:54:55PM -0700, Tobias Killer wrote: My suggested solution is to itemize those paragraphs. So, I would transform the Markdown code to But beforehand, I'd like to see PR #1418 merged. @maiska, @unman, are there any reasons for not merging that PR?

I'll do that merge when I get back home. I hope over the weekend. I see no issue with itemizing the lists, and can create PR to merge after #1418.

maiska · 2024-09-20T18:30:29Z

@tokideveloper I fixed the most important errors. Formatting, such as newlines, fonts, etc. could be done after the conversion to rst imho. Would you like to take another look? :)

https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/

tokideveloper · 2024-09-21T08:10:36Z

@maiska, thank you for fixing the most important errors!

I could take another look but beforehand, I'd like to see the newline issue to be solved (by itemizing those paragraphs, see my previous post) since it's crucial IMHO and can easily be fixed in the Markdown version. Note that I don't see no other way to solve that problem (see my previous post). Trying to fix it in the RST version won't be easier than fixing it in the Markdown version.

If you give me your "Go!", I can help you by solving the newline issue in the Markdown version. (I ask for your „Go!“, because I want to avoid double work).

maiska · 2024-09-21T10:18:47Z

@tokideveloper yeah, sure! let's sync work tho

maiska · 2024-09-24T14:47:20Z

Status update: now i am going over all the minor formatting errors/mishaps and fix them where it is easy to do so. Here is an overall final TODO list: https://github.com/maiska/qubes-translation-utilz/blob/main/README.md#final-todos

tokideveloper · 2024-10-30T20:31:56Z

@maiska: Today and yesterday, I reviewed the current state. I compared https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/ with https://www.qubes-os.org/doc/ .

Overall, it looks much better than before! 🙂 However, I've still found many differences. This time, I list them by issue.

Here is the list:

Wrong title sizes
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/
  - Titles “User Documentation”, “Developer Documentation” and “External Documentation” should be larger than their containing titles.
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/advanced-topics/i3.html#compilation-and-installation-from-source
  - This title should be larger than its subtitles.
Indented Note
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/introduction/intro.html#features
Bold font instead of italics
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/introduction/intro.html#qubes-allows-you-to-compartmentalize-your-digital-life
  - “will”
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/introduction/intro.html#made-to-support-vulnerable-users-and-power-users-alike
  - “you”, “must”
Missing monospaced font in certain links (hard to solve)
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/introduction/getting-started.html#user-interface
  - “sys-whonix”
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/introduction/faq.html#how-do-i-access-my-external-drive
  - “sys-usb”
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/introduction/issue-tracking.html#search-tips
  - “reason:completed”, “reason:"not planned"”
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/introduction/issue-tracking.html#resolution
  - “completed”, “not planned”
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/introduction/support.html
  - “qubes-users”
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/introduction/support.html#i-didn-t-find-a-solution-or-an-answer
  - “qubes-users”
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/introduction/support.html#where-s-the-best-place-to-discuss-qubes
  - “qubes-users”
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/how-to-guides/how-to-update.html#security-updates
  - “qubes-secpack”
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/how-to-guides/how-to-update.html#aem-resealing-after-updating
  - “README”
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/how-to-guides/how-to-use-devices.html#attaching-a-device-to-several-vms
  - “qvm-device block”, “qvm-block”
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/how-to-guides/how-to-use-usb-devices.html#finding-the-right-usb-controller
  - “qvm-pci”
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/how-to-guides/how-to-use-pci-devices.html#qvm-pci-usage
  - “qvb-device pci”
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/advanced-topics/bind-dirs.html#limitations
  - “/rw/config/rc.local”
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/developer/system/gui.html#appvm-guivm-messages
  - “transient_for”
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/developer/system/template-implementation.html#private-img-xvdb
  - “/home” in link “are not copied to the child TemplateBasedVM’s /home”
Missing links
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/introduction/getting-started.html#how-to-guides
  - “How-To Guides”
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/introduction/faq.html
  - “intentionally written in Markdown so as to be readable as plain text for this very reason”
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/introduction/support.html#i-have-a-problem-or-a-question
  - “How-To Guides”, “Troubleshooting”
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/templates/debian/debian-upgrade.html#how-to-upgrade-a-debian-template-in-place
  - In red box: “install a new Debian template” and “here”.
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/developer/system/architecture.html#key-architecture-features
  - “System Documentation” in the last sentence.
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/developer/system/gui.html#appvm-guivm-messages
  - “X Font cursors” in the big table.
“Important” boxes where bold font would be sufficient (not sure whether this is intentional)
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/introduction/faq.html#how-does-qubes-os-compare-to-using-a-separate-physical-machine
  - “Pros”, “Cons”
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/developer/general/usability-ux.html#easy-to-use
  - “Interfaces Should Not”, “Interfaces Should”
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/developer/general/usability-ux.html#easy-to-understand
  - “Avoid Acronyms”, “Use Simple Words”, “Avoid Technical Words”, “Use Common Concepts”, “Avoid Inconsistencies”, “Make Things Consistent”, “Avoid Duplicate Words”, “Create Groups & Categories”
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/developer/general/usability-ux.html#easy-to-complete
  - “Don’t Leave Users Stranded”, “Offer Actionable Solutions”, “Minimize Repetitive Steps”
“Note:” in bold font in RST version while not in Markdown version (minor (and not really an) issue)
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/introduction/faq.html#why-don-t-you-fix-upstream-bugs-that-affect-qubes-os
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/introduction/support.html#qubes-users
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/introduction/support.html#qubes-devel
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/introduction/support.html#qubes-project
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/introduction/support.html#qubes-translation
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/introduction/support.html#unofficial-venues
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/introduction/statistics.html#how-is-the-userbase-estimated
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/security-in-qubes/split-gpg.html#subkey-tutorials-and-discussions
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/advanced-topics/resize-disk-image.html#increasing-the-size-of-disk-images-1
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/developer/general/developing-gui-applications.html#running-programs-using-mock-qubes-object
“Warning:” in bold font in RST version while not in Markdown version (minor (and not really an) issue)
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/templates/templates.html#switching
Special formattings
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/downloading-installing-upgrading/installation-guide.html#hardware-requirements
  - “nested virtualization” -> Should be in bold font instead of italics. (minor issue)
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/downloading-installing-upgrading/installation-guide.html#installation-summary
  - “Did you know?” in the first box should be in bold font.
  - The first box should be green.
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/downloading-installing-upgrading/installation-guide.html#installation-destination
  - “Did you know?” in the third box should be in bold font.
  - “/boot” in the third box should be in monospaced font.
  - The third box should be green.
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/downloading-installing-upgrading/testing.html#providing-feedback
  - Missing special Font Awesome characters fa-thumbs-up and fa-thumbs-down missing. (minor issue)
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/how-to-guides/how-to-update.html#command-line-interface
  - In the red box, “qubes-dom0-update”, “dnf update” and „apt update“ are in italics instead of monospaced font. (I'm not sure wheather this is already a proper solution.)
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/how-to-guides/how-to-use-usb-devices.html#with-qubes-device-manager
  - The text “sys-usb:2-5 - 058f_USB_2.0_Camera” is in bold font but should be in monospaced font (which is more important IMHO).
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/advanced-topics/config-files.html#qubes-specific-vm-config-files
  - “online vif12.0 vif 10.137.0.100” should be in monospaced font.
Misleading Content
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/introduction/faq.html#should-i-trust-this-website
  - “This website is hosted on GitHub Pages (why?).” and so on.
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/security-in-qubes/ctap-proxy.html#the-qubes-approach-to-ctap
  - The text above the image states “(click fo full size)”. However, the image does not contain a link to the image file (as it does in the Markdown version).
- https://www.qubes-os.org/doc/how-to-edit-the-documentation/
  - That page is about Markdown and should be adapted to RST.
- https://www.qubes-os.org/doc/documentation-style-guide/
  - That page is about Markdown and should be adapted to RST.
Missing paragraph break in list
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/hardware/system-requirements.html#important-notes
  - between “operating systems on the same hardware.” and “Intel maintains a list of end-of-support dates”. Put the new paragraph in a subitem.
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/downloading-installing-upgrading/upgrade/3_2.html#upgrading-dom0
  - between “simply replace it with .rpmnew file.” and “If you are using Debian-based VM”. Put both paragraphs in subitems.
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/templates/templates.html#switching
  - between “and with the correct substitutions.” and “In the App Menu, click on Terminal Emulator”.
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/advanced-topics/config-files.html#gui-and-audio-configuration-in-dom0
  - The paragraph starting with “Note:” should be a subitem.
Not up-to-date image
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/hardware/certified-hardware.html#nitropad-v56
Missing yellow top box reading “Caution: This page is intended for advanced users.”
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/downloading-installing-upgrading/testing.html
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/templates/fedora/fedora-upgrade.html
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/templates/debian/debian-upgrade.html
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/templates/minimal-templates.html
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/advanced-topics/how-to-install-software-in-dom0.html
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/advanced-topics/volume-backup-revert.html
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/advanced-topics/standalones-and-hvms.html
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/advanced-topics/config-files.html
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/advanced-topics/secondary-storage.html
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/advanced-topics/rpc-policy.html
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/advanced-topics/usb-qubes.html
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/advanced-topics/managing-vm-kernels.html
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/advanced-topics/salt.html
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/advanced-topics/gui-domain.html
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/advanced-topics/disposable-customization.html
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/advanced-topics/installing-contributed-packages.html
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/advanced-topics/bind-dirs.html
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/advanced-topics/gui-configuration.html
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/advanced-topics/resize-disk-image.html
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/advanced-topics/qubes-service.html
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/advanced-topics/mount-from-other-os.html
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/advanced-topics/kde.html
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/advanced-topics/i3.html
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/advanced-topics/awesomewm.html
Unwanted paragraph break within a list item (Probably wrong intendation of subsequent lines in Markdown file)
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/how-to-guides/how-to-back-up-restore-and-migrate.html#choosing-a-backup-passphrase
Broken links
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/how-to-guides/how-to-install-software.html#installing-software-from-other-sources
  - Link “The Applications tab in Qube Settings” below image is broken (404 error). Also, that link does not exist in the Markdown version.
Broken paragraph in Markdown version
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/how-to-guides/how-to-install-software.html#full-revert
  - First list item
Superfluous-looking asterisk next to bold text in the Markdown version
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/how-to-guides/how-to-install-software.html#installing-snap-packages
  - in list item number 3, after “app qube”
Strange things
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/how-to-guides/how-to-use-disposables.html#how-to-create-named-disposables
  - In both Markdown and RST version, the last word appears to be “disposable_”. However, That word is a link in the RST version, pointing to #id1 which does not exist.
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/how-to-guides/how-to-use-pci-devices.html#attaching-devices-using-the-gui
  - Concerning item number 1, first subitem, both Markdown and RST version need to be reviewed.
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/advanced-topics/bind-dirs.html#what-is-it-useful-for
  - The link “Tor’s data dir /var/lib/tor has been made persistent in the TemplateBased ProxyVM sys-whonix” in Markdown has been shortened to “has been made persistent” in RST. But this seems to be intentional.
Superfluous image subtitles
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/developer/services/qrexec-internals.html#dom0-request-execution-of-cmd-in-domx
  - Image title “qrexec internals diagram dom0-vm” below that image does not exist in Markdown version.
- https://www.qubes-os.org/doc/qrexec-internals/#domx-request-execution-of-service-adminservice-in-dom0
  - Image title “qrexec internals diagram vm-dom0” below that image does not exist in Markdown version.
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/developer/services/qrexec-internals.html#domx-invoke-execution-of-qubes-service-qubes-service-in-domy
  - Image title “qrexec internals diagram vm-vm” below that image does not exist in Markdown version.
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/developer/services/admin-api.html#components
  - Image title “Admin API Architecture” below that image does not exist in Markdown version.
Image not offset (minor issue)
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/how-to-guides/how-to-use-devices.html#general-qubes-device-widget-behavior-and-handling
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/how-to-guides/how-to-use-devices.html#detaching-using-the-widget
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/how-to-guides/how-to-use-block-storage-devices.html#using-the-devices-widget-to-attach-a-drive
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/how-to-guides/how-to-use-block-storage-devices.html#attaching-a-file
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/how-to-guides/how-to-use-usb-devices.html#with-qubes-device-manager
  - three times
Broken tables
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/templates/templates.html#inheritance-and-persistence
  - “Inheritance1” should read just “Inheritance”.
  - “app qubes” should read “app qube³”.
  - Several snippets should be in monospaced font.
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/security-in-qubes/split-gpg.html#setup-description
  - All cells should be in monospaced font.
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/developer/services/admin-api.html#the-calls
  - Above the “note” column, there is a superfluous “i”.
  - In “description must be the last one and is the only one allowed to contain spaces”, “description” should be in monospaced font.
  - In the row with “admin.vm.property.Get”, the text “Type list is added in R4.1. Each list entry is suffixed with a newline character.” is missing in column “note”.
  - Sometimes, “vm” should not be in monospaced font.
  - Sometimes (but not every time), there is a “\n” in the Markdown version but not in the RST version. I'm not sure which one is correct.
Mistakes in Markdown version
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/templates/fedora/fedora-upgrade.html#detailed-instructions-for-standard-fedora-templates
  - In list item number 3, subitem 2, the text “At least X MB more space needed on the / filesystem.” shall be in monospaced font.
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/troubleshooting/hvm-troubleshooting.html#hvm-crashes-when-booting-from-iso
  - The text “qvm-prefs kernel” should be in monospaced font.
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/troubleshooting/gui-troubleshooting.html#screen-blanks-weird-computer-glitches-like-turning-partially-black-or-black-boxes
  - The text “Q → System Tools → Window Manager Tweaks → Compositor → uncheck “Enable display compositing”” shall be in monospaced font.
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/security-in-qubes/firewall.html#introduction
  - The last sentence “For details of that usage see here” should end with a period.
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/developer/general/developing-gui-applications.html
  - In the last sentence, “Extending the mock Qubes object” should be a link.
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/developer/system/gui.html#appvm-guivm-messages
  - Above the table, there is a </tr>, rendered as text.
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/developer/services/dom0-secure-updates.html#secure-update-mechanism-we-use-in-qubes-starting-from-beta-2
  - Two text snippets are crossed out but should be in monospaced font.
Broken monospaced text
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/advanced-topics/rpc-policy.html#rpc-policies
  - “allow``ed without any prompts. When an operation is initiated without a specific target, e.g. ``qvm-copy some_file”
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/advanced-topics/gui-configuration.html#video-ram-adjustment-for-high-resolution-displays
  - “$WIDTH``× ``$HEIGHT”
Too many space characters in monospaced text
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/advanced-topics/rpc-policy.html#rpc-policies
  - @anyvm @anyvm
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/downloading-installing-upgrading/upgrade/3_2.html#upgrading-dom0
  - yum info qubes-core-dom0
Special characters
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/templates/templates.html#trusting-your-templates
  - last paragraph: Should read “Game Over™” instead of “Game OverTM”.
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/advanced-topics/disposable-customization.html#introduction
  - “by clicking “<<”” should read “by clicking “«””.
Broken lists
- https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/developer/services/qrexec.html#policy-files
  - The last paragraph should have a list. But that list is rendered as inline text.

maiska · 2024-10-31T19:14:18Z

@tokideveloper thank you very much, i'll take a look :)

unman · 2024-11-01T13:45:43Z

@maiska Thanks for good work. I've been offline for a while and have a number of PRs that I will be pushing up over the weekend. I should be done by 11/04. So I would suggest that you rebuild the site for comparison after that. Good with you? unman

maiska · 2024-12-27T11:47:01Z

Hey @unman
Thank you so much, it is still wip, since i have to merge @tokideveloper 's fixes and incorporate some new ones into the pull request. Also there is a deprecated sphinx extension for striking through words (regarding sphinx build) which I have to find a way to fix. Though the last one is not particularly related to the pull request and independent but fyi. Let me get back to you here!
All the best,
m

marmarek mentioned this pull request Jan 5, 2024

Replace _doc submodule with redirects to rtd site QubesOS/qubesos.github.io#243

Open

marmarek force-pushed the rst2 branch 3 times, most recently from aabf0f9 to 0324e69 Compare January 8, 2024 03:25

andrewdavidwong added the reviewer needed label Jan 8, 2024

tokideveloper suggested changes May 20, 2024

View reviewed changes

marmarek added 5 commits May 21, 2024 20:59

Convert to RST

b93b3c5

Import attachment repo

4a3b08f

Import only files used in the documentation (and their source files if applicable). Based on c3f45c81842d6c5df064fce385b464b4041b3b62 in qubes-attachment repo.

manual fixes

bbd0337

Manual fixes after the conversion tool.

Update index

a71b86a

gsoc: remove outdated projects

47f39e1

Not only comment them, really remove.

marmarek force-pushed the rst2 branch from 0324e69 to 47f39e1 Compare May 21, 2024 20:07

maiska reviewed May 25, 2024

View reviewed changes

andrewdavidwong removed the reviewer needed label May 26, 2024

andrewdavidwong mentioned this pull request May 28, 2024

Transition the Qubes documentation to the Read the Docs (RTD) platform QubesOS/qubes-issues#8180

Open

6 tasks

tokideveloper mentioned this pull request Jul 16, 2024

Translation - scripts, the final part QubesOS/qubesos.github.io#154

Open

maiska mentioned this pull request Aug 11, 2024

Preparation for rst conversion #1418

Open



		locale_dirs = ['_translated']

Convert all the documentation to Sphinx / RST #1367

Are you sure you want to change the base?

Convert all the documentation to Sphinx / RST #1367

Conversation

marmarek commented Jan 5, 2024 • edited Loading

marmarek commented Jan 5, 2024

tokideveloper left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

marmarek commented May 20, 2024

marmarek commented May 21, 2024

tokideveloper commented May 23, 2024

tokideveloper commented May 23, 2024

andrewdavidwong commented May 23, 2024

tokideveloper commented May 24, 2024

andrewdavidwong commented May 24, 2024

tokideveloper commented May 25, 2024

tokideveloper commented May 25, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tokideveloper commented May 25, 2024 • edited Loading

tokideveloper commented May 25, 2024

andrewdavidwong commented May 25, 2024

marmarek commented May 25, 2024

tokideveloper commented May 26, 2024

tokideveloper commented May 26, 2024

tokideveloper commented May 26, 2024 • edited Loading

tokideveloper commented May 26, 2024

maiska commented May 26, 2024 • edited Loading

unman commented May 27, 2024 via email

marmarek commented May 27, 2024

unman commented May 27, 2024 via email

andrewdavidwong commented May 28, 2024 • edited Loading

tokideveloper commented May 31, 2024

maiska commented Jun 1, 2024 • edited Loading

maiska commented Aug 11, 2024

maiska commented Aug 11, 2024

maiska commented Aug 11, 2024 • edited Loading

tokideveloper commented Aug 17, 2024

tokideveloper commented Aug 19, 2024

maiska commented Aug 19, 2024

tokideveloper commented Aug 24, 2024

unman commented Aug 24, 2024 via email

maiska commented Sep 20, 2024 • edited Loading

tokideveloper commented Sep 21, 2024

maiska commented Sep 21, 2024

maiska commented Sep 24, 2024 • edited Loading

tokideveloper commented Oct 30, 2024

maiska commented Oct 31, 2024

unman commented Nov 1, 2024 via email

maiska commented Dec 27, 2024

marmarek commented Jan 5, 2024 •

edited

Loading

tokideveloper commented May 25, 2024 •

edited

Loading

tokideveloper commented May 26, 2024 •

edited

Loading

maiska commented May 26, 2024 •

edited

Loading

andrewdavidwong commented May 28, 2024 •

edited

Loading

maiska commented Jun 1, 2024 •

edited

Loading

maiska commented Aug 11, 2024 •

edited

Loading

maiska commented Sep 20, 2024 •

edited

Loading

maiska commented Sep 24, 2024 •

edited

Loading