Replace _doc submodule with redirects to rtd site #243

marmarek · 2024-01-05T13:21:36Z

Counterpart to QubesOS/qubes-doc#1479

This currently redirects to the https://doc.qubes-os.org/en/latest/.

marmarek · 2024-01-05T16:29:37Z

testDeploy

marmarek · 2024-01-08T10:28:21Z

PipelineRefresh

marmarek · 2024-01-08T10:28:37Z

testDeploy

marmarek · 2025-07-04T16:12:23Z

testDeploy

marmarek · 2025-07-04T17:08:48Z

testDeploy

marmarek · 2025-07-04T17:38:28Z

testDeploy

tokideveloper

I reviewed this PR. I tried to be as thorough as possible. However, sometimes I could not decide whether something is right or wrong.

tokideveloper · 2025-08-10T13:26:05Z

.gitlab-ci.yml

+  script:
+    - git clone https://gitlab.com/${CI_PROJECT_PATH%%/*}/qubesos.github.io ~/qubesos.github.io -b test
+    - ~/qubesos.github.io/_utils/gitlabci.sh


I can't say whether this is right or wrong. I'm not an expert here. To be reviewed by someone else.

tokideveloper · 2025-08-10T14:04:36Z

_data/architecture.yml

+    url: https://doc.qubes-os.org/en/latest/index.html#introduction
  - title: Choosing hardware
-    url: /doc/#choosing-your-hardware
+    url: https://doc.qubes-os.org/en/latest/index.html#choosing-your-hardware
  - title: Installing and upgrading
-    url: /doc/#downloading-installing-and-upgrading-qubes
+    url: https://doc.qubes-os.org/en/latest/index.html#downloading-installing-and-upgrading-qubes
  - title: How-to guides
-    url: /doc/#how-to-guides
+    url: https://doc.qubes-os.org/en/latest/index.html#how-to-guides
  - title: Templates
-    url: /doc/#templates
+    url: https://doc.qubes-os.org/en/latest/index.html#templates
  - title: Troubleshooting
-    url: /doc/#troubleshooting
+    url: https://doc.qubes-os.org/en/latest/index.html#troubleshooting
  - title: Security in Qubes
-    url: /doc/#security-in-qubes
+    url: https://doc.qubes-os.org/en/latest/index.html#security-in-qubes
  - title: Project security
-    url: /doc/#project-security
+    url: https://doc.qubes-os.org/en/latest/index.html#project-security
  - title: Developer docs
-    url: /doc/#developer-documentation
+    url: https://doc.qubes-os.org/en/latest/index.html#developer-documentation
  - title: External docs
-    url: /doc/#external-documentation
+    url: https://doc.qubes-os.org/en/latest/index.html#external-documentation


Not sure, whether modifying these links is necessary. There is a redirect for /doc/ in this PR. Is it to get the fragments/anchors working? I didn't manage it to generate the website on this branch.

Unfortunately it is necessary. The /doc/ redirect discards the section (the part after #), so it would point at the top of index, not specific place. I don't think it's technically possible to do a redirect that preserves the section anchor.
Applies to all other places like this.

tokideveloper · 2025-08-10T14:17:19Z

_data/downloads-page.yml

    - column: URL
  links:
-    - url: /downloads/mirrors/#instructions-for-mirror-operators
+    - url: https://doc.qubes-os.org/en/latest/user/downloading-installing-upgrading/download-mirrors.html#instructions-for-mirror-operators


tokideveloper · 2025-08-10T14:18:22Z

_data/hcl.yml

      text: Motherboards
      id: 3
-    - url: /doc/how-to-use-the-hcl/#generating-and-submitting-new-reports
+    - url: https://doc.qubes-os.org/en/latest/user/hardware/how-to-use-the-hcl.html#generating-and-submitting-new-reports


tokideveloper · 2025-08-10T14:18:32Z

_data/hcl.yml

      text: What is the hardware compatibility list (HCL)?
      id: 1
-    - url: /doc/how-to-use-the-hcl/#generating-and-submitting-new-reports
+    - url: https://doc.qubes-os.org/en/latest/user/hardware/how-to-use-the-hcl.html#generating-and-submitting-new-reports


tokideveloper · 2025-08-10T18:01:47Z

_includes/variables.html

  {% endif %}
 <!-- Doc link -->
-  {% assign doc_link = lang | append: "/doc/" %}
+  {% assign doc_link = "https://doc.qubes-os.org/" | append: page.lang | append: "/latest/index.html" %}


Since page.lang could be nil, I suggest the following lines instead of this line 72:

{% if page.lang == nil %} {% assign doclang = "en" %} {% else %} {% assign doclang = page.lang %} {% endif %} {% assign doc_link = "https://doc.qubes-os.org/" | append: doclang | append: "/latest/index.html" %}

tokideveloper · 2025-08-10T18:06:09Z

_utils/gitlabci.sh

+#temp fixup
+git remote set-url origin $(git remote get-url origin | sed -e s/gitlab/github/)
+


I can't say whether this is right or wrong. I'm not an expert here. To be reviewed by someone else.

tokideveloper · 2025-08-10T18:38:45Z

_doc/developer/general/documentation-style-guide.md

+
+### Image linking
+
+See [how to add images](https://doc.qubes-os.org/en/latest/developer/general/how-to-edit-the-documentation.html#how-to-add-images) for the required syntax. This will make the image a hyperlink to the image file, allowing the reader to click on the image in order to view the full image by itself. This is important. Following best practices, our website has a responsive design, which allows the website to render appropriately across all screen sizes. When viewing this page on a smaller screen, such as on a mobile device, the image will automatically shrink down to fit the screen. If visitors cannot click on the image to view it in full size, then, depending on their device, they may have no way see the details in the image clearly.


This link redirects to
https://www.qubes-os.org/doc/how-to-edit-the-documentation/
missing the anchor/fragment #how-to-add-images.

In order to fix it, I suggest to link to
https://www.qubes-os.org/doc/how-to-edit-the-documentation/#how-to-add-images
directly or using magic:
/doc/how-to-edit-the-documentation/#how-to-add-images

However, I did not test my suggestion.

tokideveloper · 2025-08-10T18:44:30Z

_doc/developer/general/documentation-style-guide.md

+
+### Core vs. external documentation
+
+Core documentation resides in the [Qubes OS Project's official repositories](https://github.com/QubesOS/), mainly in [qubes-doc](https://github.com/QubesOS/qubes-doc). External documentation can be anywhere else (such as forums, community websites, and blogs), but there is an especially large collection in the [Qubes Forum](https://forum.qubes-os.org/docs). External documentation should not be submitted to [qubes-doc](https://github.com/QubesOS/qubes-doc). If you've written a piece of documentation that is not appropriate for [qubes-doc](https://github.com/QubesOS/qubes-doc), we encourage you to submit it to the [Qubes Forum](https://forum.qubes-os.org/docs) instead. However, *linking* to external documentation from [qubes-doc](https://github.com/QubesOS/qubes-doc) is perfectly fine. Indeed, the maintainers of the [Qubes Forum](https://forum.qubes-os.org/) should regularly submit PRs against the documentation index (see [How to edit the documentation index](https://doc.qubes-os.org/en/latest/developer/general/how-to-edit-the-documentation.html#how-to-edit-the-documentation-index)) to add and update Qubes Forum links in the ["External documentation"](https://qubes-doc-rst.readthedocs.io/en/latest/index.html#external-documentation) section of the documentation table of contents.


Same thing here:
https://doc.qubes-os.org/en/latest/developer/general/how-to-edit-the-documentation.html#how-to-edit-the-documentation-index
redirects to
https://www.qubes-os.org/doc/how-to-edit-the-documentation/
missing #how-to-edit-the-documentation-index.

Either link to
https://www.qubes-os.org/doc/how-to-edit-the-documentation/#how-to-edit-the-documentation-index
directly or use magic via
/doc/how-to-edit-the-documentation/#how-to-edit-the-documentation-index

Not tested.

tokideveloper · 2025-08-10T18:46:47Z

_doc/developer/general/documentation-style-guide.md

+
+The main difference between **core** (or **official**) and **external** (or **community** or **unofficial**) documentation is whether it documents software that is officially written and maintained by the Qubes OS Project. The purpose of this distinction is to keep the core docs maintainable and high-quality by limiting them to the software output by the Qubes OS Project. In other words, we take responsibility for documenting all of the software we put out into the world, but it doesn't make sense for us to take on the responsibility of documenting or maintaining documentation for anything else. For example, Qubes OS may use a popular Linux distribution for an official [TemplateVM](/doc/templates/). However, it would not make sense for a comparatively small project like ours, with modest funding and a lean workforce, to attempt to document software belonging to a large, richly-funded project with an army of paid and volunteer contributors, especially when they probably already have documentation of their own. This is particularly true when it comes to Linux in general. Although many users who are new to Qubes are also new to Linux, it makes absolutely no sense for our comparatively tiny project to try to document Linux in general when there is already a plethora of documentation out there.
+
+Many contributors do not realize that there is a significant amount of work involved in *maintaining* documentation after it has been written. They may wish to write documentation and submit it to the core docs, but they see only their own writing process and fail to consider that it will have to be kept up-to-date and consistent with the rest of the docs for years afterward. Submissions to the core docs also have to [undergo a review process](https://doc.qubes-os.org/en/latest/developer/general/how-to-edit-the-documentation.html#security) to ensure accuracy before being merged, which takes up valuable time from the team. We aim to maintain high quality standards for the core docs (style and mechanics, formatting), which also takes up a lot of time. If the documentation involves anything external to the Qubes OS Project (such as a website, platform, program, protocol, framework, practice, or even a reference to a version number), the documentation is likely to become outdated when that external thing changes. It's also important to periodically review and update this documentation, especially when a new Qubes release comes out. Periodically, there may be technical or policy changes that affect all the core documentation. The more documentation there is relative to maintainers, the harder all of this will be. Since there are many more people who are willing to write documentation than to maintain it, these individually small incremental additions amount to a significant maintenance burden for the project.


Same thing here:
https://doc.qubes-os.org/en/latest/developer/general/how-to-edit-the-documentation.html#security
redirects to
https://www.qubes-os.org/doc/how-to-edit-the-documentation/

Link to
https://www.qubes-os.org/doc/how-to-edit-the-documentation/#security
directly or use magic
/doc/how-to-edit-the-documentation/#security

Not tested.

maiska · 2025-09-07T16:00:14Z

pages/home.html

  <div class="white-box more-bottom">
    <div class="row">
-      <p>Have questions or need a hand? As a free and open-source project, our valued community of users and contributors from around the world are in the best position to help. Before diving in, we encourage you to read about <a href="/support/#staying-safe">staying safe</a>, our <a href="/support/#discussion-guidelines">discussion guidelines</a>, and our <a href="/code-of-conduct/">code of conduct</a> to help keep things positive and on-track. We welcome newcomers and returning users wanting to discuss Qubes and <a href="/doc/contributing/">seeking to contribute</a>.
+      <p>Have questions or need a hand? As a free and open-source project, our valued community of users and contributors from around the world are in the best position to help. Before diving in, we encourage you to read about <a href="https://doc.qubes-os.org/en/latest/introduction/support.html#staying-safe">staying safe</a>, our <a href="https://qubes-doc-rst.readthedocs.io/en/latest/introduction/support.html#discussion-guidelines">discussion guidelines</a>, and our <a href="/code-of-conduct/">code of conduct</a> to help keep things positive and on-track. We welcome newcomers and returning users wanting to discuss Qubes and <a href="/doc/contributing/">seeking to contribute</a>.


href here should be https://doc.qubes-os.org/en/latest/introduction/support.html#discussion-guidelines and not https://qubes-doc-rst.readthedocs.io/en/latest/introduction/support.html#discussion-guidelines

maiska · 2025-09-07T16:03:23Z

_doc/CONTRIBUTING.md

@@ -0,0 +1,12 @@
+# Contributing to `qubes-doc`


The content will be updated later as well as contributing.md in the root dir

maiska · 2025-09-07T16:03:50Z

_doc/README.md

@@ -0,0 +1,11 @@
+# Qubes OS Documentation
+


The content will be updated later as well as README.md in root dir

Redirects break section anchors, so put target links directly there.

Is is not a submodule anymore

marmarek · 2025-09-11T13:58:54Z

testDeploy

marmarek force-pushed the rst-redirects branch 2 times, most recently from 7226b13 to 4953d5d Compare January 5, 2024 14:48

qubesos-bot temporarily deployed to qa January 5, 2024 16:59 Inactive

marmarek force-pushed the rst-redirects branch 2 times, most recently from 5980236 to 3d1861f Compare January 8, 2024 04:09

andrewdavidwong added the reviewer needed label Jan 8, 2024

qubesos-bot temporarily deployed to qa January 8, 2024 10:28 Inactive

marmarek mentioned this pull request May 27, 2024

Convert all the documentation to Sphinx / RST QubesOS/qubes-doc#1367

Closed

marmarek force-pushed the rst-redirects branch 2 times, most recently from c189169 to 6611e84 Compare July 4, 2025 15:55

qubesos-bot temporarily deployed to qa July 4, 2025 16:12 Inactive

marmarek force-pushed the rst-redirects branch 2 times, most recently from 541e636 to 74c25a1 Compare July 4, 2025 16:31

qubesos-bot temporarily deployed to qa July 4, 2025 17:08 Inactive

marmarek force-pushed the rst-redirects branch from 50cbbe7 to 358b4c2 Compare July 4, 2025 17:22

qubesos-bot temporarily deployed to qa July 4, 2025 17:38 Inactive

tokideveloper reviewed Aug 10, 2025

View reviewed changes

parulin mentioned this pull request Aug 16, 2025

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

Closed

maiska reviewed Sep 7, 2025

View reviewed changes

marmarek added 3 commits September 11, 2025 15:18

Replace _doc submodule with redirects to rtd site

e37e03a

Update links in architecture.yml

9a22477

Redirects break section anchors, so put target links directly there.

Update other links to specific sections

2ea01ee

Redirects break section anchors, so put target links directly there.

marmarek force-pushed the rst-redirects branch from 358b4c2 to be15cb7 Compare September 11, 2025 13:27

Update _posts submodule for updated links

5775176

marmarek added 2 commits September 11, 2025 15:46

ci: use test branch temporarily

b27a45f

Remove _doc from update-submodules script

22d4063

Is is not a submodule anymore

marmarek force-pushed the rst-redirects branch from 8cb315b to 22d4063 Compare September 11, 2025 13:46

qubesos-bot temporarily deployed to qa September 11, 2025 13:58 Inactive

marmarek merged commit 22d4063 into QubesOS:main Sep 11, 2025
1 check failed

marmarek temporarily deployed to github-pages September 11, 2025 14:02 — with GitHub Pages Inactive

marmarek mentioned this pull request Sep 12, 2025

change sphinx output format to dirhtml QubesOS/qubes-doc#1530

Open

		#temp fixup
		git remote set-url origin $(git remote get-url origin \| sed -e s/gitlab/github/)


		### Image linking

		See [how to add images](https://doc.qubes-os.org/en/latest/developer/general/how-to-edit-the-documentation.html#how-to-add-images) for the required syntax. This will make the image a hyperlink to the image file, allowing the reader to click on the image in order to view the full image by itself. This is important. Following best practices, our website has a responsive design, which allows the website to render appropriately across all screen sizes. When viewing this page on a smaller screen, such as on a mobile device, the image will automatically shrink down to fit the screen. If visitors cannot click on the image to view it in full size, then, depending on their device, they may have no way see the details in the image clearly.


		### Core vs. external documentation

		Core documentation resides in the [Qubes OS Project's official repositories](https://github.com/QubesOS/), mainly in [qubes-doc](https://github.com/QubesOS/qubes-doc). External documentation can be anywhere else (such as forums, community websites, and blogs), but there is an especially large collection in the [Qubes Forum](https://forum.qubes-os.org/docs). External documentation should not be submitted to [qubes-doc](https://github.com/QubesOS/qubes-doc). If you've written a piece of documentation that is not appropriate for [qubes-doc](https://github.com/QubesOS/qubes-doc), we encourage you to submit it to the [Qubes Forum](https://forum.qubes-os.org/docs) instead. However, linking to external documentation from [qubes-doc](https://github.com/QubesOS/qubes-doc) is perfectly fine. Indeed, the maintainers of the [Qubes Forum](https://forum.qubes-os.org/) should regularly submit PRs against the documentation index (see [How to edit the documentation index](https://doc.qubes-os.org/en/latest/developer/general/how-to-edit-the-documentation.html#how-to-edit-the-documentation-index)) to add and update Qubes Forum links in the ["External documentation"](https://qubes-doc-rst.readthedocs.io/en/latest/index.html#external-documentation) section of the documentation table of contents.


		The main difference between core (or official) and external (or community or unofficial) documentation is whether it documents software that is officially written and maintained by the Qubes OS Project. The purpose of this distinction is to keep the core docs maintainable and high-quality by limiting them to the software output by the Qubes OS Project. In other words, we take responsibility for documenting all of the software we put out into the world, but it doesn't make sense for us to take on the responsibility of documenting or maintaining documentation for anything else. For example, Qubes OS may use a popular Linux distribution for an official [TemplateVM](/doc/templates/). However, it would not make sense for a comparatively small project like ours, with modest funding and a lean workforce, to attempt to document software belonging to a large, richly-funded project with an army of paid and volunteer contributors, especially when they probably already have documentation of their own. This is particularly true when it comes to Linux in general. Although many users who are new to Qubes are also new to Linux, it makes absolutely no sense for our comparatively tiny project to try to document Linux in general when there is already a plethora of documentation out there.

		Many contributors do not realize that there is a significant amount of work involved in maintaining documentation after it has been written. They may wish to write documentation and submit it to the core docs, but they see only their own writing process and fail to consider that it will have to be kept up-to-date and consistent with the rest of the docs for years afterward. Submissions to the core docs also have to [undergo a review process](https://doc.qubes-os.org/en/latest/developer/general/how-to-edit-the-documentation.html#security) to ensure accuracy before being merged, which takes up valuable time from the team. We aim to maintain high quality standards for the core docs (style and mechanics, formatting), which also takes up a lot of time. If the documentation involves anything external to the Qubes OS Project (such as a website, platform, program, protocol, framework, practice, or even a reference to a version number), the documentation is likely to become outdated when that external thing changes. It's also important to periodically review and update this documentation, especially when a new Qubes release comes out. Periodically, there may be technical or policy changes that affect all the core documentation. The more documentation there is relative to maintainers, the harder all of this will be. Since there are many more people who are willing to write documentation than to maintain it, these individually small incremental additions amount to a significant maintenance burden for the project.

Uh oh!

Replace _doc submodule with redirects to rtd site #243

Replace _doc submodule with redirects to rtd site #243

Uh oh!

Conversation

marmarek commented Jan 5, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

marmarek commented Jan 5, 2024

Uh oh!

marmarek commented Jan 8, 2024

Uh oh!

marmarek commented Jan 8, 2024

Uh oh!

marmarek commented Jul 4, 2025

Uh oh!

marmarek commented Jul 4, 2025

Uh oh!

marmarek commented Jul 4, 2025

Uh oh!

tokideveloper left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

marmarek commented Sep 11, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

marmarek commented Jan 5, 2024 •

edited

Loading