Merge remote-tracking branch 'origin/main' into update-devices-widget-icon

conf.py

@@ -31,6 +31,7 @@ release = '4.2.4'
 
 extensions = [
   'sphinx.ext.autosectionlabel',  # Automatically generate section labels
+  'sphinx.ext.intersphinx',  # Reference other doc projects
   'sphinxnotes.strike', # Add strike-through text support
   'sphinx_reredirects', # Manage redirects in the documentation
   'sphinxext.opengraph', # Add Open Graph meta tags for social media sharing
@@ -49,7 +50,6 @@ redirects = {
         "https://www.qubes-os.org/downloads/",
 }
 
-
 # -- -- Options for highlighting ---------------------------------------------
 
 # Disable syntax highlighting
@@ -101,6 +101,15 @@ linkcheck_ignore = [r'^https?://[^/\s]+\.onion']
 # Prefix section labels with the document name
 autosectionlabel_prefix_document = True
 
+# Allows references to the docs in dev.qubes-os.org
+# i.e.: :doc:`core-admin:libvirt`
+intersphinx_mapping = {
+    'core-admin': ('https://dev.qubes-os.org/projects/core-admin/en/latest/', None),
+    'core-admin-client': ('https://dev.qubes-os.org/projects/core-admin-client/en/latest/', None),
+    'core-qrexec': ('https://dev.qubes-os.org/projects/qubes-core-qrexec/en/stable/', None),
+}
+intersphinx_disabled_reftypes = ["*"]
+
 # Open Graph image for social media sharing
 ogp_image = "https://www.qubes-os.org/attachment/icons/qubes-logo-icon-name-slogan-fb.png"
 # Disable Open Graph image alt text

developer/debugging/windows-debugging.rst

@@ -23,7 +23,7 @@ Modifying the NIC of the target VM
 ----------------------------------
 
 
-You will need to create a custom libvirt config for the target VM. See `the documentation <https://dev.qubes-os.org/projects/core-admin/en/latest/libvirt.html>`__ for overview of how libvirt templates work in Qubes. The following assumes the target VM is named ``target-vm``.
+You will need to create a :doc:`custom libvirt config <core-admin:libvirt>` for the target VM. The following assumes the target VM is named ``target-vm``.
 
 - Edit ``/usr/share/qubes/templates/libvirt/xen.xml`` to prepare our custom config to override just the NIC part of the global template:
 

developer/general/how-to-edit-the-rst-documentation.rst

@@ -119,7 +119,7 @@ You will be able to adjust the pull request message and title there. In
 most cases, the defaults are ok, so you can just confirm by pressing the
 :guilabel:`Create pull request` button again. However, if you’re not ready for
 your PR to be reviewed or merged yet, please
-`make a draft PR instead <https://github.blog/2019-02-14-introducing-draft-pull-requests/>`__.
+`make a draft PR instead <https://github.blog/news-insights/product-news/introducing-draft-pull-requests/>`__.
 
 |pull-request-confirm|
 

developer/general/rst-documentation-style-guide.rst

@@ -239,7 +239,7 @@ These render as:
 
 .. note::
        **Note:** Using Rufus to create the installation medium means that you
-       `won't be able <"https://github.com/QubesOS/qubes-issues/issues/2051">`__
+       `won't be able <https://github.com/QubesOS/qubes-issues/issues/2051>`__
        to choose the "Test this media and install Qubes OS" option mentioned in the
        example below. Instead, choose the "Install Qubes OS" option.
 
@@ -295,7 +295,6 @@ Please continue using the above or new ones where appropriate.
 Cross referencing:
 ^^^^^^^^^^^^^^^^^^
 
-
 - Use the `:doc:` role with a path and a custom link text:
 
 
@@ -330,6 +329,42 @@ and link to the section from within the documentation using :code:`:ref:`cross_r
 
 For further information please see :ref:`cross_referencing`.
 
+External cross-referencing
+""""""""""""""""""""""""""
+
+You can make a cross-reference to any of the projects of the external developer's documentation (hosted on https://dev.qubes-os.org):
+
+* :doc:`core-admin <core-admin:index>`
+* :doc:`core-admin-client <core-admin-client:index>`
+* :doc:`core-qrexec <core-qrexec:index>`
+
+To do such a cross-reference, use the usual cross-reference syntax but with the following prefix: :samp:`{PROJECT_NAME}:` (replace :samp:`{PROJECT_NAME}` by the name of the project). As an example, if you want to link to the index of the core-admin documentation, use this:
+
+.. list-table::
+   :widths: 50 50
+   :header-rows: 1
+
+   * - reStructuredText markup
+     - output
+   * - .. code:: rst
+
+          :doc:`core-admin:index`
+
+     - :doc:`core-admin:index`
+
+This is equivalent to using ``:doc:`index``` inside the core-admin documentation. This works with any role like ``:ref:``, ``:option:``, etc.
+
+Even if it works without it, always prefix the external cross-references with the name of the project, to help other contributors and maintainers to figure out what is going on.
+
+.. note::
+
+   Intersphinx `can list all the available links <https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#showing-all-links-of-an-intersphinx-mapping-file>`__ to another project with the following command:
+
+   .. code:: console
+
+       python3 -m sphinx.ext.intersphinx https://dev.qubes-os.org/projects/core-admin/en/latest/objects.inv
+
+   You can replace ``core-admin`` by any of the projects listed above.
 
 Hyperlink syntax
 ^^^^^^^^^^^^^^^^
@@ -466,7 +501,7 @@ Indentation
 ^^^^^^^^^^^
 
 Use spaces instead of tabs. Use hanging indentations where appropriate.
-rST is identation sensitiv markup language, similar to Python, please maintain consistent indentation (3 spaces) for readability.
+rST is an indentation sensitive markup language, similar to Python, please maintain consistent indentation (3 spaces) for readability.
 
 
 Line wrapping
@@ -474,7 +509,6 @@ Line wrapping
 
 Do not hard wrap text, except where necessary (e.g., inside code blocks).
 
-
 Writing guidelines
 ------------------
 
@@ -571,7 +605,7 @@ Capitalization of "qube"
 
 We introduced the term :term:`qube` as a user-friendly alternative to the term :term:`vm` in the context of Qubes OS. Nonetheless, “qube” is a common noun like the words “compartment” and “container.” Therefore, in English, “qube” follows the standard capitalization rules for common nouns. For example, “I have three qubes” is correct, while “I have three Qubes” is incorrect. Like other common nouns, “qube” should still be capitalized at the beginnings of sentences, the beginnings of sentence-case headings, and in title-case headings. Note, however, that starting a sentence with the plural of “qube” (e.g., “Qubes can be shut down…”) can be ambiguous, since it may not be clear whether the referent is a plurality of qubes, :term:`qubes os`, or even the Qubes OS Project itself. Hence, it is generally a good idea to rephrase such sentences in order to avoid this ambiguity.
 
-Many people feel a strong temptation to capitalize the word “qube” all the time, like a proper noun, perhaps because it’s a new and unfamiliar term that’s closely associated with a particular piece of software (namely, Qubes OS). However, these factors are not relevant to the capitalization rules of English. In fact, it’s not unusual for new common nouns to be introduced into English, especially in the context of technology. For example, “blockchain” is a relatively recent technical term that’s a common noun. Why is it a common noun rather than a proper noun? Because proper nouns refer to *particular* people, places, things, and ideas. There are many different blockchains. However, even when there was just one, the word still denoted a collection of things rather than a particular thing. It happened to be the case that there was only one member in that collection at the time. For example, if there happened to be only one tree in the world, that wouldn’t change the way we capitalize sentences like, “John sat under a tree.” Intuitively, it makes sense that the addition and removal of objects from the world shouldn’t cause published books to become orthographicallly incorrect while sitting on their shelves.
+Many people feel a strong temptation to capitalize the word “qube” all the time, like a proper noun, perhaps because it’s a new and unfamiliar term that’s closely associated with a particular piece of software (namely, Qubes OS). However, these factors are not relevant to the capitalization rules of English. In fact, it’s not unusual for new common nouns to be introduced into English, especially in the context of technology. For example, “blockchain” is a relatively recent technical term that’s a common noun. Why is it a common noun rather than a proper noun? Because proper nouns refer to *particular* people, places, things, and ideas. There are many different blockchains. However, even when there was just one, the word still denoted a collection of things rather than a particular thing. It happened to be the case that there was only one member in that collection at the time. For example, if there happened to be only one tree in the world, that wouldn’t change the way we capitalize sentences like, “John sat under a tree.” Intuitively, it makes sense that the addition and removal of objects from the world shouldn’t cause published books to become orthographically incorrect while sitting on their shelves.
 
 Accordingly, the reason “qube” is a common noun rather than a proper noun is because it doesn’t refer to any one specific thing (in this case, any one specific virtual machine). Rather, it’s the term for any virtual machine in a Qubes OS installation. (Technically, while qubes are currently implemented as virtual machines, Qubes OS is independent of its underlying compartmentalization technology. Virtual machines could be replaced with a different technology, and qubes would still be called “qubes.”)
 
@@ -724,8 +758,8 @@ Cheatsheet: Markdown vs. reStructuredText
 For the documentation contributors more familiar with Markdown, here is a small cheatsheet
 highlighting essential differences.
 
-Headings
+Cheatsheet: Headings
-^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^
 
 **Markdown:**
 
@@ -802,8 +836,8 @@ Text Decoration
         **Bold**
         :strike:`Strikethrough`
 
-Lists
+Cheatsheet: Lists
-^^^^^
+^^^^^^^^^^^^^^^^^
 
 **Markdown:**
 
@@ -833,8 +867,8 @@ Lists
            a. Subitem 1
            b. Subitem 2
 
-Tables
+Cheatsheet: Tables
-^^^^^^
+^^^^^^^^^^^^^^^^^^
 
 **Markdown:**
 
@@ -861,8 +895,8 @@ Tables
            * - Cell 3
              - Cell 4
 
-Code Blocks
+Cheatsheet: Code Blocks
-^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^
 
 **Markdown:**
     .. code:: markdown

developer/releases/4_3/schedule.rst

@@ -14,6 +14,10 @@ The table below is based on our :ref:`release schedule policy <developer/release
 
    * - Date
      - Stage
-   * - TBD
+   * - 2025-08-10
      - 4.3.0-rc1 release
+   * - 2025-09-19
+     - 4.3.0-rc2 release
+   * - 2025-10-20
+     - 4.3.0-rc3 release
 

developer/system/template-manager.rst

@@ -83,7 +83,7 @@ The file structure should be quite similar to previous template RPMs. Namely, th
 
   - Uses ``KEY=VALUE`` format.
 
-  - Fields (corresponding to `qvm-prefs <https://dev.qubes-os.org/projects/core-admin-client/en/stable/manpages/qvm-prefs.html#common-properties>`__ and `qvm-features <https://dev.qubes-os.org/projects/core-admin-client/en/stable/manpages/qvm-features.html#list-of-known-features>`__ tags with the same names)
+  - Fields (corresponding to :doc:`qvm-prefs <core-admin-client:manpages/qvm-prefs>` and :doc:`qvm-features <core-admin-client:manpages/qvm-features>` tags with the same names)
 
     - ``virt_mode``
 

index.rst

@@ -2,7 +2,6 @@
 Documentation
 =============
 
-
 =================
 Table of contents
 =================

introduction/intro.rst

@@ -13,68 +13,58 @@ What is Qubes OS?
 Qubes OS is a free and open-source, security-oriented operating system for
 single-user desktop computing. Qubes OS `leverages Xen-based virtualization <https://wiki.xen.org/wiki/Xen_Project_Software_Overview>`__ to allow for the creation and management of isolated compartments called :term:`qubes <qube>`.
 
+These qubes, which are implemented as :term:`virtual machines (VMs) <vm>`, have specific:
 
-These qubes, which are implemented as :term:`virtual machines (VMs)<VM>`, have specific:
+- **Purposes:** with a predefined set of one or many isolated applications, for personal or professional projects, to manage the :doc:`network stack </developer/system/networking>`, :doc:`the firewall </user/security-in-qubes/firewall>`, or to fulfill other user-defined purposes.
 
-- **Purposes:** with a predefined set of one or many isolated
+- **Natures:** :doc:`full-fledged </user/advanced-topics/standalones-and-hvms>` or :doc:`stripped-down </introduction/getting-started/>` virtual machines based on popular operating systems, such as :doc:`Fedora </user/templates/fedora/fedora>`, :doc:`Debian </user/templates/debian/debian>`, and :doc:`Windows </user/templates/windows/windows>`.
-  applications, for personal or professional projects, to manage the
-  :doc:`network stack </developer/system/networking>`, :doc:`the firewall </user/security-in-qubes/firewall>`, or to fulfill other
-  user-defined purposes.
 
-- **Natures:** :doc:`full-fledged </user/advanced-topics/standalones-and-hvms>` or
+- **Levels of trust:** from complete to non-existent. All windows are displayed in a unified desktop environment with :doc:`unforgeable colored window borders </introduction/getting-started>` so that different security levels are easily identifiable.
-  :doc:`stripped-down </introduction/getting-started/>` virtual machines based on popular operating systems,
-  such as :doc:`Fedora </user/templates/fedora/fedora>`, :doc:`Debian </user/templates/debian/debian>`, and
-  :doc:`Windows </user/templates/windows/windows>`.
-               
-- **Levels of trust:** from complete to non-existent. All windows are displayed in a unified desktop environment with
-  :doc:`unforgeable colored window borders </introduction/getting-started>` so that different security levels are easily identifiable.
 
-.. figure:: /attachment/site/qubes-trust-level-architecture.png
+.. image:: /attachment/site/qubes-trust-level-architecture.png
    :alt: Qubes system diagram
 
-
 .. note::
 
-      **Note:** See our :doc:`glossary </user/reference/glossary>` and :doc:`FAQ </introduction/faq>` for more information.
+      See our :doc:`/user/reference/glossary` and :doc:`/introduction/faq` for more information.
-
 
 Features
 --------
 
-- **Strong isolation** Isolate different pieces of software as if they were installed on separate
+Strong isolation
-  physical machines using advanced virtualization techniques.
+   Isolate different pieces of software as if they were installed on separate physical machines using advanced virtualization techniques.
 
-- **Template system** Use :term:`app qubes  <app qube>` to
+Template system
-  share a root file system without sacrificing security using the innovative
+   Use :term:`app qubes <app qube>` to share a root file system without sacrificing security using the innovative :doc:`Template system </user/templates/templates>`.
-  :doc:`Template system </user/templates/templates>`.
 
+Multiple operating systems
+   Use multiple operating systems at the same time, including :doc:`Fedora </user/templates/fedora/fedora>`, :doc:`Debian </user/templates/debian/debian/>`, and :doc:`Windows </user/templates/windows/windows>`
 
-- **Multiple operating systems** Use multiple operating systems at the same time, including
+:term:`Disposables <disposable>`
-  :doc:`Fedora </user/templates/fedora/fedora>`, :doc:`Debian </user/templates/debian/debian/>`, and
+   Create :doc:`disposables </user/how-to-guides/how-to-use-disposables>` on the fly that self-destruct when shut down.
-  :doc:`Windows </user/templates/windows/windows>`         
 
-- **Disposables** Create :doc:`disposables </user/how-to-guides/how-to-use-disposables>` on the fly that self-destruct when shut down.
+Whonix integration
+   Run `Tor <https://www.torproject.org/>`__ securely system-wide using `Whonix with Qubes <https://www.whonix.org/wiki/Qubes>`__.
 
-- **Whonix integration** Run `Tor <https://www.torproject.org/>`__ securely system-wide using `Whonix with Qubes <https://www.whonix.org/wiki/Qubes>`__.
+Device isolation
+   Secure :doc:`device handling </user/how-to-guides/how-to-use-devices>` through isolation of network cards and USB controllers.
 
-- **Device isolation** Secure :doc:`device handling </user/how-to-guides/how-to-use-devices>` through isolation of network cards and USB controllers.
+Split GPG
+   Utilize :doc:`Split GPG </user/security-in-qubes/split-gpg>` to keep your private keys safe.
 
-- **Split GPG** Utilize :doc:`Split GPG </user/security-in-qubes/split-gpg>` to keep your private keys safe.
+CTAP proxy
-
+   Operate :doc:`Qubes CTAP proxy </user/security-in-qubes/ctap-proxy>` to use your two-factor authentication devices without exposing your web browser to the full USB stack.
-- **CTAP proxy** Operate :doc:`Qubes CTAP proxy </user/security-in-qubes/ctap-proxy>` to use your two-factor authentication devices without exposing your web browser to the full USB stack.
-
-- **Open-source** Users are free to use, copy, and modify Qubes OS and :doc:`are encouraged to do so! </introduction/contributing>`
 
+Open-source
+   Users are free to use, copy, and modify Qubes OS and :doc:`are encouraged to do so! </introduction/contributing>`
 
 .. note::
 
-      **Note:** Given the technical nature of Qubes OS, prior experience with Linux can be helpful.
+      Given the technical nature of Qubes OS, prior experience with Linux can be helpful.
-
 
 Why Qubes OS?
 -------------
 
-
 Physical isolation is a given safeguard that the digital world lacks
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -95,11 +85,9 @@ Better yet, it allows us to create new compartments whenever we need them,
 and it gives us sophisticated tools for securely managing our activities
 and data across these compartments.
 
-.. figure:: /attachment/doc/r4.0-qubes-manager.png
+.. image:: /attachment/doc/r4.0-qubes-manager.png
    :alt: Qubes manager
 
-
-
 Qubes allows you to compartmentalize your digital life
 ------------------------------------------------------
 
@@ -126,13 +114,12 @@ physical computer without having to worry about a single successful
 cyberattack taking down your entire digital life in one fell swoop. In
 fact, Qubes has `distinct advantages over physical air gaps <https://invisiblethingslab.com/resources/2014/Software_compartmentalization_vs_physical_separation.pdf>`__.
 
-.. figure:: /attachment/site/qubes-partition-data-flows.jpg
+.. image:: /attachment/site/qubes-partition-data-flows.jpg
    :alt: Compartmentalization example
 
 Made to support vulnerable users and power users alike
 ------------------------------------------------------
 
-
 Qubes provides practical, usable security to vulnerable and
 actively-targeted individuals, such as journalists, activists,
 whistleblowers, and researchers. Qubes is designed with the understanding
@@ -157,31 +144,18 @@ software, because the fundamental operating system that constitutes the
 core infrastructure of our digital lives **must** be free and
 open-source in order to be trustworthy.
 
-
+.. image:: /attachment/doc/r4.0-snapshot12.png
-.. figure:: /attachment/doc/r4.0-snapshot12.png
    :alt: Qubes desktop screenshot
 
+Qubes OS at a glance
+--------------------
 
-
+:doc:`/introduction/video-tours/`
-Video Tours
+   Want to see Qubes OS in action? Sit back and watch one of the guided :doc:`/introduction/video-tours/`!
-^^^^^^^^^^^
+:doc:`/introduction/screenshots/`
-
+   See what using Qubes actually looks like with various applications running in Qubes.
-Want to see Qubes OS in action? Sit back and watch a guided :doc:`tour! </introduction/video-tours/>`
+:doc:`/introduction/getting-started`
-
+   Ready to get started with Qubes? Find all you need to know after installing.
-
-Screenshots
-^^^^^^^^^^^
-
-See what using Qubes actually looks like with these :doc:`screenshots </introduction/screenshots/>` of various
-applications running in Qubes.
-
-
-Getting Started
-^^^^^^^^^^^^^^^
-
-Ready to get started with Qubes? :doc:`Here's </introduction/getting-started>` what you need to know after installing.
-
-
 
 More information
 ----------------
@@ -190,7 +164,6 @@ This page is just a brief introduction to what Qubes is all about, and
 many technical details have been omitted here for the sake of
 presentation.
 
-
 - If you’re a current or potential Qubes user, you may want to check out the :doc:`documentation </index>` and the :ref:`user FAQ <introduction/faq:users>`.
 - If you’re a developer, there’s dedicated :ref:`index:Developer Documentation` and a :ref:`developer FAQ <introduction/faq:developers>` just for you.
 - Ready to give Qubes a try? Head on over to the `downloads page <https://www.qubes-os.org/downloads/>`__, and read the :doc:`Installation guide </user/downloading-installing-upgrading/installation-guide>`.

user/how-to-guides/how-to-enter-fullscreen-mode.rst

@@ -51,7 +51,7 @@ Enabling fullscreen mode from a selected qube
 
 .. warning:: Be sure to read :ref:`secure-use-of-fullscreen-mode` first.
 
-As an alternative to the Xfce4 method, you can enable fullscreen mode for selected qubes by using the `gui-allow-fullscreen <https://dev.qubes-os.org/projects/core-admin-client/en/latest/manpages/qvm-features.html#gui-gui-default>`__ feature of a qube.
+As an alternative to the Xfce4 method, you can enable fullscreen mode for selected qubes by using a :doc:`gui-* <core-admin-client:manpages/qvm-features>` feature called ``gui-allow-fullscreen``.
 
 Be sure to restart the qube after modifying this feature, for the changes to take effect.
 

user/reference/tools.rst

@@ -7,11 +7,8 @@ Dom0
 ----
 
 
-- `core-admin <https://dev.qubes-os.org/projects/core-admin/en/latest/manpages/>`__
+- :doc:`core-admin <core-admin:manpages/index>`
-
+- :doc:`core-admin-client <core-admin-client:manpages/index>`
-- `core-admin-client <https://dev.qubes-os.org/projects/core-admin-client/en/latest/manpages/>`__
-
-
 
 DomU
 ----