From c40c0ac30203f4a9647f69ca7dbe8d9c219650d0 Mon Sep 17 00:00:00 2001 From: parulin <161326115+parulin@users.noreply.github.com> Date: Sat, 13 Sep 2025 04:30:59 -0400 Subject: [PATCH 1/8] Install intersphinx extension and edit links Some anchor links are currently lost on: * developer/system/template-manager.rst * user/how-to-guides/how-to-enter-fullscreen-mode.rst --- conf.py | 8 +++++++- developer/debugging/windows-debugging.rst | 2 +- developer/system/template-manager.rst | 2 +- user/how-to-guides/how-to-enter-fullscreen-mode.rst | 2 +- user/reference/tools.rst | 7 ++----- 5 files changed, 12 insertions(+), 9 deletions(-) diff --git a/conf.py b/conf.py index a0fcd220..fa20b541 100644 --- a/conf.py +++ b/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,12 @@ 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 +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), +} + # 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 diff --git a/developer/debugging/windows-debugging.rst b/developer/debugging/windows-debugging.rst index ce219540..68f927e4 100644 --- a/developer/debugging/windows-debugging.rst +++ b/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 `__ 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 :external:doc:`custom libvirt config ` 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: diff --git a/developer/system/template-manager.rst b/developer/system/template-manager.rst index aad21181..811ed60d 100644 --- a/developer/system/template-manager.rst +++ b/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 `__ and `qvm-features `__ tags with the same names) + - Fields (corresponding to :external:doc:`qvm-prefs ` and :external:doc:`qvm-features ` tags with the same names) - ``virt_mode`` diff --git a/user/how-to-guides/how-to-enter-fullscreen-mode.rst b/user/how-to-guides/how-to-enter-fullscreen-mode.rst index 40696a6b..82deec2c 100644 --- a/user/how-to-guides/how-to-enter-fullscreen-mode.rst +++ b/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 `__ feature of a qube. +As an alternative to the Xfce4 method, you can enable fullscreen mode for selected qubes by using the :external:doc:`gui-allow-fullscreen ` feature of a qube. Be sure to restart the qube after modifying this feature, for the changes to take effect. diff --git a/user/reference/tools.rst b/user/reference/tools.rst index 14927dfa..8315b6d5 100644 --- a/user/reference/tools.rst +++ b/user/reference/tools.rst @@ -7,11 +7,8 @@ Dom0 ---- -- `core-admin `__ - -- `core-admin-client `__ - - +- :external+core-admin:doc:`core-admin ` +- :external+core-admin-client:doc:`core-admin-client ` DomU ---- From b052a987219843de70967cedd1cb9796b9a38f6c Mon Sep 17 00:00:00 2001 From: parulin <161326115+parulin@users.noreply.github.com> Date: Sat, 13 Sep 2025 08:53:36 -0400 Subject: [PATCH 2/8] Add core-qrexec to the intersphinx mappings --- conf.py | 1 + 1 file changed, 1 insertion(+) diff --git a/conf.py b/conf.py index fa20b541..7cdec396 100644 --- a/conf.py +++ b/conf.py @@ -105,6 +105,7 @@ autosectionlabel_prefix_document = True 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), } # Open Graph image for social media sharing From 1a47fc973bde8ce9cd25d5d1580d47f4fe2cb2c7 Mon Sep 17 00:00:00 2001 From: parulin <161326115+parulin@users.noreply.github.com> Date: Sat, 13 Sep 2025 17:13:33 -0400 Subject: [PATCH 3/8] Add intersphinx documentation and clean syntax * I replaced the `:external:` syntax by a cleaner one, as suggested by @maiska. * An implicit external reference is now impossible. * Fix duplicate labels warnings * Minor typos, including the word "orthographicallly" :) --- conf.py | 2 + developer/debugging/windows-debugging.rst | 2 +- .../general/rst-documentation-style-guide.rst | 114 +++++++----------- developer/system/template-manager.rst | 2 +- index.rst | 1 + .../how-to-enter-fullscreen-mode.rst | 2 +- user/reference/tools.rst | 4 +- 7 files changed, 54 insertions(+), 73 deletions(-) diff --git a/conf.py b/conf.py index 7cdec396..f557617b 100644 --- a/conf.py +++ b/conf.py @@ -102,11 +102,13 @@ linkcheck_ignore = [r'^https?://[^/\s]+\.onion'] 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" diff --git a/developer/debugging/windows-debugging.rst b/developer/debugging/windows-debugging.rst index 68f927e4..dd0d0471 100644 --- a/developer/debugging/windows-debugging.rst +++ b/developer/debugging/windows-debugging.rst @@ -23,7 +23,7 @@ Modifying the NIC of the target VM ---------------------------------- -You will need to create a :external:doc:`custom libvirt config ` for the target VM. The following assumes the target VM is named ``target-vm``. +You will need to create a :doc:`custom libvirt config ` 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: diff --git a/developer/general/rst-documentation-style-guide.rst b/developer/general/rst-documentation-style-guide.rst index 8d4f2091..3b4f92db 100644 --- a/developer/general/rst-documentation-style-guide.rst +++ b/developer/general/rst-documentation-style-guide.rst @@ -19,7 +19,6 @@ If you’re not familiar with reStructuredText syntax, `the Sphinx primer `__. Please always be mindful that rST syntax is sensitive to indentation! - Directives ^^^^^^^^^^ @@ -102,8 +101,6 @@ By specifying the language, you enable pygments, which show syntax color coding code - - Use ``[...]`` for anything omitted. For inlining small code snippets you can use the `code role `__ as in @@ -122,7 +119,6 @@ You can add line numbers to code examples with the ``:linenos:`` parameter. def hello_world(): print("Hello, world!") - You can have certain lines with the ``:emphasize-lines:`` parameter. .. code:: rst @@ -130,8 +126,6 @@ You can have certain lines with the ``:emphasize-lines:`` parameter. .. code:: python :emphasize-lines: 1,3,4 - - For Python use ``python``. .. code:: rst @@ -172,7 +166,6 @@ For text use ``text``. some text - Tables """""" @@ -228,8 +221,6 @@ Here are examples of several types of alerts: compromised hardware. Do not install Qubes on a computer you don't trust. See installation security for more information. - - These render as: .. hint:: @@ -239,7 +230,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 `__ to choose the "Test this media and install Qubes OS" option mentioned in the example below. Instead, choose the "Install Qubes OS" option. @@ -255,7 +246,6 @@ These render as: compromised hardware. Do not install Qubes on a computer you don't trust. See installation security for more information. - Glossary """""""" @@ -264,7 +254,6 @@ is created with a simple ``.. glossary::`` block in :file:`/user/reference/gloss Anywhere else in the documentation you can link to a term using the role: :code:`:term:`qube`` which automatically generates a hyperlink to the glossary entry :term:`qube`. - Roles ^^^^^ @@ -291,7 +280,6 @@ Some of the roles used in the Qubes OS documentation so far are: Please continue using the above or new ones where appropriate. - Cross referencing: ^^^^^^^^^^^^^^^^^^ @@ -301,21 +289,54 @@ Use the `:doc:` role with a path :doc:`contributions `. - use `:ref:` for specific sections .. code:: rst :ref:`qubes ` - 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 ` +* :doc:`core-admin-client ` +* :doc:`core-qrexec ` + +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 `__ 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 ^^^^^^^^^^^^^^^^ - Use non-reference-style links like .. code:: rst @@ -334,7 +355,6 @@ This facilitates the localization process. Take a look also at :ref:`cross_referencing`. - Relative vs. absolute links ^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -353,26 +373,22 @@ instead of: You may use absolute URLs in the following cases: - - External links - URLs that appear inside code blocks (e.g., in comments and document templates, and the plain text reproductions of `QSBs `__ and `Canaries `__), since they’re not hyperlinks - Git repo files like ``README.md`` and ``CONTRIBUTING.md``, since they’re not part of the documentation itself. - This rule is important because using absolute URLs for internal website links breaks: - Serving the documentation offline - Documentation localization - Generating offline documentation - HTML and CSS ^^^^^^^^^^^^ Do not write HTML inside rST documents. In particular, never include HTML or CSS for styling, formatting, or white space control. That belongs in the (S)CSS files instead. - Headings ^^^^^^^^ @@ -383,7 +399,6 @@ as long as they are in consistent use across the documentation. Qubes OS uses the convention in `Python Developer’s Guide for documenting `__ which are as follows: - .. code:: text # with overline, for parts @@ -410,14 +425,11 @@ A simple example of how this is used in the Qubes OS documentation: Paragraph """"""""" - - Text decorations ^^^^^^^^^^^^^^^^ Emphasis and Italics - - *Italics*: Use single asterisks .. code:: rst @@ -436,26 +448,22 @@ Emphasis and Italics ``monospace`` - Paragraph ^^^^^^^^^ Paragraphs are plain texts where indentation matters. Separate paragraphs by leaving a blank line between them. - 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. - Line wrapping ^^^^^^^^^^^^^ Do not hard wrap text, except where necessary (e.g., inside code blocks). - Writing guidelines ------------------ @@ -486,7 +494,6 @@ When providing command-line examples: $ echo Hello Hello - - Precede each command with the appropriate command prompt: At a minimum, the prompt should contain a trailing ``#`` (for the user ``root``) or ``$`` (for other users) on Linux systems and ``>`` on Windows systems, respectively. - Don’t try to add comments inside the code block. For example, *don’t* do this: @@ -505,27 +512,21 @@ When providing command-line examples: The ``#`` symbol preceding each comment is ambiguous with a root command prompt. Instead, put your comments *outside* of the code block in normal prose. - Variable names in commands ^^^^^^^^^^^^^^^^^^^^^^^^^^ - Syntactically distinguish variables in commands. For example, this is ambiguous: .. code:: console $ qvm-run --dispvm=disposable-template --service qubes.StartApp+xterm - - It should instead be: .. code:: console $ qvm-run --dispvm= --service qubes.StartApp+xterm - - Note that we syntactically distinguish variables in three ways: 1. Surrounding them in angled brackets (``< >``) @@ -534,8 +535,6 @@ Note that we syntactically distinguish variables in three ways: 3. Using all capital letters - - We have observed that many novices make the mistake of typing the surrounding angled brackets (``< >``) on the command line, even after substituting the desired real value between them. Therefore, in documentation aimed at novices, we also recommend clarifying that the angled brackets should not be typed. This can be accomplished in one of several ways: - Explicitly say something like “without the angled brackets.” @@ -544,15 +543,12 @@ We have observed that many novices make the mistake of typing the surrounding an - If you know that almost all users will want to use (or should use) a specific command containing all real values and no variables, you might consider providing exactly that command and forgoing the version with variables. Novices may not realize which parts of the command they can substitute with different values, but if you’ve correctly judged that they should use the command you’ve provided as is, then this shouldn’t matter. - - 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.”) @@ -561,23 +557,19 @@ I have several qubes in my Qubes OS installation, and you have several in yours. English language conventions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - For the sake of consistency and uniformity, the Qubes documentation aims to follow the conventions of American English, where applicable. (Please note that this is an arbitrary convention for the sake consistency and not a value judgment about the relative merits of British versus American English.) Organizational guidelines ------------------------- - Do not duplicate documentation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - Duplicating documentation is almost always a bad idea. There are many reasons for this. The main one is that almost all documentation has to be updated as some point. When similar documentation appears in more than one place, it is very easy for it to get updated in one place but not the others (perhaps because the person updating it doesn’t realize it’s in more than once place). When this happens, the documentation as a whole is now inconsistent, and the outdated documentation becomes a trap, especially for novice users. Such traps are often more harmful than if the documentation never existed in the first place. The solution is to **link** to existing documentation rather than duplicating it. There are some exceptions to this policy (e.g., information that is certain not to change for a very long time), but they are rare. Core vs. external documentation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - Core documentation resides in the `Qubes OS Project’s official repositories `__, mainly in `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 `__. External documentation should not be submitted to `qubes-doc `__. If you’ve written a piece of documentation that is not appropriate for `qubes-doc `__, we encourage you to submit it to the `Qubes Forum `__ instead. However, *linking* to external documentation from `qubes-doc `__ is perfectly fine. Indeed, the maintainers of the `Qubes Forum `__ should regularly submit PRs against the documentation index (see :ref:`edit_doc_index`) to add and update Qubes Forum links in the :ref:`“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 :doc:`TemplateVM `. 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. @@ -588,11 +580,9 @@ On the positive side, we consider the existence of community documentation to be See `#4693 `__ for more background information. - Release-specific documentation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - *See* `#5308 `__ *for pending changes to this policy.* We maintain only one set of documentation for Qubes OS. We do not maintain a different set of documentation for each release of Qubes. Our single set of Qubes OS documentation is updated on a continual, rolling basis. Our first priority is to document all **current, stable releases** of Qubes. Our second priority is to document the next, upcoming release (if any) that is currently in the beta or release candidate stage. @@ -604,7 +594,6 @@ In general, avoid mentioning specific Qubes versions in the body text of documen Incorrect Example ^^^^^^^^^^^^^^^^^ - .. code:: rst How to Foo @@ -627,12 +616,9 @@ Incorrect Example Once you foo, make sure to close the baz before fooing the next bar. - - Correct Example ^^^^^^^^^^^^^^^ - .. code:: rst Qubes 3.2 @@ -673,8 +659,6 @@ Correct Example Once you foo, make sure to close the baz before fooing the next bar. - - Subdividing the page into clearly-labeled sections for each release has several benefits: - It preserves good content for older (but still supported) releases. Many documentation contributors are also people who prefer to use the latest release. Many of them are tempted to *replace* existing content that applies to an older, supported release with content that applies only to the latest release. This is somewhat understandable. Since they only use the latest release, they may be focused on their own experience, and they may even regard the older release as deprecated, even when it’s actually still supported. However, allowing this replacement of content would do a great disservice to those who still rely on the older, supported release. In many cases, these users value the stability and reliability of the older, supported release. With the older, supported release, there has been more time to fix bugs and make improvements in both the software and the documentation. Consequently, much of the documentation content for this release may have gone through several rounds of editing, review, and revision. It would be a tragedy for this content to vanish while the very set of users who most prize stability and reliability are depending on it. @@ -685,8 +669,6 @@ Subdividing the page into clearly-labeled sections for each release has several - It’s easy for documentation contributors and maintainers to know which file to edit and update, since there’s only one page for all Qubes OS releases. Initially creating the new headings and duplicating content that applies to both is only a one-time cost for each page, and many pages don’t even require this treatment, since they apply to all currently-supported Qubes OS releases. - - By contrast, an alternative approach, such as segregating the documentation into two different branches, would mean that contributions that apply to both Qubes releases would only end up in one branch, unless someone remembered to manually submit the same thing to the other branch and actually made the effort to do so. Most of the time, this wouldn’t happen. When it did, it would mean a second pull request that would have to be reviewed. Over time, the different branches would diverge in non-release-specific content. Good general content that was submitted only to one branch would effectively disappear once that release was deprecated. (Even if it were still on the website, no one would look at it, since it would explicitly be in the subdirectory of a deprecated release, and there would be a motivation to remove it from the website so that search results wouldn’t be populated with out-of-date information.) For further discussion about release-specific documentation in Qubes, see `here `__. @@ -694,19 +676,16 @@ For further discussion about release-specific documentation in Qubes, see `here Git conventions --------------- - Please follow our :ref:`Git commit message guidelines `. - - Cheatsheet: Markdown vs. reStructuredText ----------------------------------------- For the documentation contributors more familiar with Markdown, here is a small cheatsheet highlighting essential differences. -Headings -^^^^^^^^ +Cheatsheet: Headings +^^^^^^^^^^^^^^^^^^^^ **Markdown:** @@ -761,7 +740,6 @@ Internal :doc:`Link Text ` - For example on cross referencing please see :ref:`cross_referencing`. Text Decoration @@ -783,8 +761,8 @@ Text Decoration **Bold** :strike:`Strikethrough` -Lists -^^^^^ +Cheatsheet: Lists +^^^^^^^^^^^^^^^^^ **Markdown:** @@ -814,8 +792,8 @@ Lists a. Subitem 1 b. Subitem 2 -Tables -^^^^^^ +Cheatsheet: Tables +^^^^^^^^^^^^^^^^^^ **Markdown:** @@ -842,8 +820,8 @@ Tables * - Cell 3 - Cell 4 -Code Blocks -^^^^^^^^^^^ +Cheatsheet: Code Blocks +^^^^^^^^^^^^^^^^^^^^^^^ **Markdown:** .. code:: markdown diff --git a/developer/system/template-manager.rst b/developer/system/template-manager.rst index 811ed60d..f43f8ee1 100644 --- a/developer/system/template-manager.rst +++ b/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 :external:doc:`qvm-prefs ` and :external:doc:`qvm-features ` tags with the same names) + - Fields (corresponding to :doc:`qvm-prefs ` and :doc:`qvm-features ` tags with the same names) - ``virt_mode`` diff --git a/index.rst b/index.rst index 8fe97090..3823f53c 100644 --- a/index.rst +++ b/index.rst @@ -2,6 +2,7 @@ Documentation ============= +:doc:`core-admin:index` ================= Table of contents diff --git a/user/how-to-guides/how-to-enter-fullscreen-mode.rst b/user/how-to-guides/how-to-enter-fullscreen-mode.rst index 82deec2c..2222af76 100644 --- a/user/how-to-guides/how-to-enter-fullscreen-mode.rst +++ b/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 :external:doc:`gui-allow-fullscreen ` feature of a qube. +As an alternative to the Xfce4 method, you can enable fullscreen mode for selected qubes by using a :doc:`gui-* ` feature called ``gui-allow-fullscreen``. Be sure to restart the qube after modifying this feature, for the changes to take effect. diff --git a/user/reference/tools.rst b/user/reference/tools.rst index 8315b6d5..95a6d53e 100644 --- a/user/reference/tools.rst +++ b/user/reference/tools.rst @@ -7,8 +7,8 @@ Dom0 ---- -- :external+core-admin:doc:`core-admin ` -- :external+core-admin-client:doc:`core-admin-client ` +- :doc:`core-admin ` +- :doc:`core-admin-client ` DomU ---- From f0709dd4831a1de4b6e6452a15a6c6212f157d44 Mon Sep 17 00:00:00 2001 From: parulin <161326115+parulin@users.noreply.github.com> Date: Sat, 13 Sep 2025 17:35:21 -0400 Subject: [PATCH 4/8] Fix minor typos and link on rst related pages --- developer/general/how-to-edit-the-rst-documentation.rst | 4 ++-- developer/general/rst-documentation-style-guide.rst | 3 +-- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/developer/general/how-to-edit-the-rst-documentation.rst b/developer/general/how-to-edit-the-rst-documentation.rst index 652725f6..c47c89dd 100644 --- a/developer/general/how-to-edit-the-rst-documentation.rst +++ b/developer/general/how-to-edit-the-rst-documentation.rst @@ -19,7 +19,7 @@ detect changes in a GitHub repository and build the latest version of a document By cloning and regularly pulling from `qubes-doc `__ repository, users can maintain their own up-to-date offline copy of the Qubes documentation rather than relying solely on the web and either serve it locally or read the rST files directly. -EPUB or PDF versions of Qubes OS documenation can also +EPUB or PDF versions of Qubes OS documentation can also be downloaded from `doc.qubes-os.org `__: .. figure:: /attachment/doc/rst-rtd-epub-pdf.png @@ -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 `__. +`make a draft PR instead `__. |pull-request-confirm| diff --git a/developer/general/rst-documentation-style-guide.rst b/developer/general/rst-documentation-style-guide.rst index 50f4a96f..7aefbfaf 100644 --- a/developer/general/rst-documentation-style-guide.rst +++ b/developer/general/rst-documentation-style-guide.rst @@ -501,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 @@ -509,7 +509,6 @@ Line wrapping Do not hard wrap text, except where necessary (e.g., inside code blocks). - Writing guidelines ------------------ From a4dd000030e9d97921b282cddf7c018f37062a1d Mon Sep 17 00:00:00 2001 From: parulin <161326115+parulin@users.noreply.github.com> Date: Wed, 17 Sep 2025 07:55:44 -0400 Subject: [PATCH 5/8] Introduction: markup changes Following the doc migration from Markdown to RestructuredText, a more logical markup was applied to the *Features* section, but not to the section about *video tours*, *screenshots* and *Getting started*. I changed that last section and ended up using a definition list also for the Features section (seems more consistent and appropriate as links are allowed in titles. The `figure` markup should be used for images with a caption or a description** --- introduction/intro.rst | 105 +++++++++++++++-------------------------- 1 file changed, 39 insertions(+), 66 deletions(-) diff --git a/introduction/intro.rst b/introduction/intro.rst index 4b70a70b..7084a12a 100644 --- a/introduction/intro.rst +++ b/introduction/intro.rst @@ -11,70 +11,60 @@ 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 `__ to allow for the creation and management of isolated compartments called :term:`qubes `. +single-user desktop computing. Qubes OS leverages `Xen-based virtualization `__ to allow for the creation and management of isolated compartments called :term:`qubes `. +These qubes, which are implemented as :term:`virtual machines (VMs) `, have specific: -These qubes, which are implemented as :ref:`virtual machines (VMs)`, have specific: - -- **Purposes:** with a predefined set of one or many isolated - applications, for personal or professional projects, to manage the - :doc:`network stack `, :doc:`the firewall `, or to fulfill other - user-defined purposes. +- **Purposes:** with a predefined set of one or many isolated applications, for personal or professional projects, to manage the :doc:`network stack `, :doc:`the firewall `, or to fulfill other user-defined purposes. -- **Natures:** :doc:`full-fledged ` or - :doc:`stripped-down ` virtual machines based on popular operating systems, - such as :doc:`Fedora `, :doc:`Debian `, and - :doc:`Windows `. - -- **Levels of trust:** from complete to non-existent. All windows are displayed in a unified desktop environment with - :doc:`unforgeable colored window borders ` so that different security levels are easily identifiable. +- **Natures:** :doc:`full-fledged ` or :doc:`stripped-down ` virtual machines based on popular operating systems, such as :doc:`Fedora `, :doc:`Debian `, and :doc:`Windows `. -.. figure:: /attachment/site/qubes-trust-level-architecture.png +- **Levels of trust:** from complete to non-existent. All windows are displayed in a unified desktop environment with :doc:`unforgeable colored window borders ` so that different security levels are easily identifiable. + +.. image:: /attachment/site/qubes-trust-level-architecture.png :alt: Qubes system diagram - .. note:: - **Note:** See our :doc:`glossary ` and :doc:`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 - physical machines using advanced virtualization techniques. +Strong isolation + Isolate different pieces of software as if they were installed on separate physical machines using advanced virtualization techniques. -- **Template system** Use :term:`app qubes ` to - share a root file system without sacrificing security using the innovative - :doc:`Template system `. +Template system + Use :term:`app qubes ` to share a root file system without sacrificing security using the innovative :doc:`Template system `. +Multiple operating systems + Use multiple operating systems at the same time, including :doc:`Fedora `, :doc:`Debian `, and :doc:`Windows ` -- **Multiple operating systems** Use multiple operating systems at the same time, including - :doc:`Fedora `, :doc:`Debian `, and - :doc:`Windows ` +:term:`Disposables ` + Create :doc:`disposables ` on the fly that self-destruct when shut down. -- **Disposables** Create :doc:`disposables ` on the fly that self-destruct when shut down. +Whonix integration + Run `Tor `__ securely system-wide using `Whonix with Qubes `__. -- **Whonix integration** Run `Tor `__ securely system-wide using `Whonix with Qubes `__. +Device isolation + Secure :doc:`device handling ` through isolation of network cards and USB controllers. -- **Device isolation** Secure :doc:`device handling ` through isolation of network cards and USB controllers. +Split GPG + Utilize :doc:`Split GPG ` to keep your private keys safe. -- **Split GPG** Utilize :doc:`Split GPG ` to keep your private keys safe. - -- **CTAP proxy** Operate :doc:`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! ` +CTAP proxy + Operate :doc:`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! ` .. 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 `__. -.. 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. - -.. figure:: /attachment/doc/r4.0-snapshot12.png +.. image:: /attachment/doc/r4.0-snapshot12.png :alt: Qubes desktop screenshot +Qubes OS at a glance +-------------------- - -Video Tours -^^^^^^^^^^^ - -Want to see Qubes OS in action? Sit back and watch a guided :doc:`tour! ` - - -Screenshots -^^^^^^^^^^^ - -See what using Qubes actually looks like with these :doc:`screenshots ` of various -applications running in Qubes. - - -Getting Started -^^^^^^^^^^^^^^^ - -Ready to get started with Qubes? :doc:`Here's ` what you need to know after installing. - - +:doc:`/introduction/video-tours/` + Want to see Qubes OS in action? Sit back and watch one of the guided tour! +:doc:`/introduction/screenshots/` + See what using Qubes actually looks like with various applications running in Qubes. +:doc:`/introduction/getting-started` + Ready to get started with Qubes? Find all you need to know after installing. More information ---------------- @@ -190,9 +164,8 @@ 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 ` and the :ref:`user FAQ `. -- If you’re a developer, there’s dedicated :ref:`index:Developer Documentation` and a :ref:`developer FAQ ` just for you. +- If you’re a developer, there’s dedicated :ref:`index:Developer Documentation`, a :ref:`developer FAQ ` and the `documentation of the source code `__, just for you. - Ready to give Qubes a try? Head on over to the `downloads page `__, and read the :doc:`Installation guide `. - Need help, or just want to join the conversation? Learn more about :doc:`help, support, the mailing lists, and the forum `. From 6d0aeb35700ba5a050529d77b7da66c8e7b48a2c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Fri, 19 Sep 2025 17:43:54 +0200 Subject: [PATCH 6/8] Update 4.3 release schedule --- developer/releases/4_3/schedule.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/developer/releases/4_3/schedule.rst b/developer/releases/4_3/schedule.rst index 56d419ab..e1305170 100644 --- a/developer/releases/4_3/schedule.rst +++ b/developer/releases/4_3/schedule.rst @@ -14,6 +14,10 @@ The table below is based on our :ref:`release schedule policy Date: Sun, 21 Sep 2025 11:43:52 -0400 Subject: [PATCH 7/8] Revert some links in intro Revert some links introduced or removed in a4dd0000 --- introduction/intro.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/introduction/intro.rst b/introduction/intro.rst index c10ed7e4..2a5e4168 100644 --- a/introduction/intro.rst +++ b/introduction/intro.rst @@ -151,7 +151,7 @@ Qubes OS at a glance -------------------- :doc:`/introduction/video-tours/` - Want to see Qubes OS in action? Sit back and watch one of the guided tour! + 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. :doc:`/introduction/getting-started` @@ -165,7 +165,7 @@ 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 ` and the :ref:`user FAQ `. -- If you’re a developer, there’s dedicated :ref:`index:Developer Documentation`, a :ref:`developer FAQ ` and the `documentation of the source code `__, just for you. +- If you’re a developer, there’s dedicated :ref:`index:Developer Documentation` and a :ref:`developer FAQ ` just for you. - Ready to give Qubes a try? Head on over to the `downloads page `__, and read the :doc:`Installation guide `. - Need help, or just want to join the conversation? Learn more about :doc:`help, support, the mailing lists, and the forum `. From 5fd9a6b52f9a1b12c9f20ecfc7e9fc7b9a95253a Mon Sep 17 00:00:00 2001 From: parulin <161326115+parulin@users.noreply.github.com> Date: Sun, 21 Sep 2025 11:48:12 -0400 Subject: [PATCH 8/8] Remove garbage content introduced with intersphinx --- .../rst-documentation-style-guide.rst.orig | 886 ------------------ index.rst | 2 - 2 files changed, 888 deletions(-) delete mode 100644 developer/general/rst-documentation-style-guide.rst.orig diff --git a/developer/general/rst-documentation-style-guide.rst.orig b/developer/general/rst-documentation-style-guide.rst.orig deleted file mode 100644 index dc30ee1e..00000000 --- a/developer/general/rst-documentation-style-guide.rst.orig +++ /dev/null @@ -1,886 +0,0 @@ -=========================================== -reStructuredText documentation style guide -=========================================== - -*Also see* :doc:`How to edit the documentation `. - -This page explains the standards we follow for writing, formatting, and organizing the documentation. -Please follow these guidelines and conventions when editing the rST documentation. -For the standards governing the website (as opposed to the rST documentation hosted on `https://doc.qubes-os.org `__), -please see the :doc:`Website style guide `. -If you wish to submit a pull request regarding content hosted on the website, please refer to -:doc:`How to edit the website `. - -reStructuredText conventions ----------------------------- - -All the documentation is written in `reStructuredText (rST) `__. When making contributions, please observe the following style conventions. -If you’re not familiar with reStructuredText syntax, `the Sphinx primer `__ -is a great resource, as well as `this quick reStructuredText `__. -Please always be mindful that rST syntax is sensitive to indentation! - -Directives -^^^^^^^^^^ - -A `directive `__ is a generic block of explicit markup, -provided by `Docutils `__ and extended by `Sphinx `__. -Directives are used to insert non-paragraph content, such as images, tables, and code blocks. -Example directives are: - -.. code:: rst - - .. image:: - .. code:: - .. figure:: - -Directives start with ``..``, followed by directive name, arguments, options, and indented content. - -Images -"""""" - -To include images (without a caption), use the ``image`` directive. -You need to specify the path to the image and an alt text. - -.. code:: rst - - .. image:: path/to/image.png - :alt: Alternative text - :width: 200px - :align: center - -Read The Docs and the HTML `sphinx-rtd-theme `__ in use -have a responsive design, which allows the documentation to render appropriately across all screen sizes. - -Make sure to link only to images in the :file:`attachment/doc` folder of the `qubes-doc `__ repository. -Do not attempt to link to images hosted on other websites. - -See also :ref:`how_to_add_images` for the further information and about using the ``figure`` directive. - -Lists -""""" - -`Lists `__ can be bullet lists (\*, +, -), enumerated lists (1., 2., etc.), definition lists, field lists. - -Nested lists must be separated from the parent list items by blank lines: - -.. code:: rst - - - Item 1 - - Item 2 - - - Subitem 2.1 - - Subitem 2.2 - - - Item 3 - -Numbered lists can be autonumbered using the ``#`` sign. - -.. code:: rst - - #. Item 1 - #. Item 2 - - #. Subitem 2.1 - #. Subitem 2.2 - - #. Item 3 - -Item 3 will start at 1. - -Code blocks -""""""""""" - -When writing code blocks, use syntax highlighting within the `code `__ -or `code-block `__. - -By specifying the language, you enable pygments, which show syntax color coding for that code sample (see `here `__ for a list of supported languages). - -.. code:: rst - - .. code:: language - - code - -Use ``[...]`` for anything omitted. - -For inlining small code snippets you can use the `code role `__ as in - -.. code:: rst - - `code:`:term:`qube`` - -You can add line numbers to code examples with the ``:linenos:`` parameter. - -.. code:: rst - - .. code:: python - :linenos: - - def hello_world(): - print("Hello, world!") - -You can have certain lines with the ``:emphasize-lines:`` parameter. - -.. code:: rst - - .. code:: python - :emphasize-lines: 1,3,4 - -For Python use ``python``. - -.. code:: rst - - .. code:: python - - string_var = 'python' - -For Bash use ``bash``. - -.. code:: rst - - .. code:: bash - - #!/bin/bash - -For a terminal session use ``console``. - -.. code:: rst - - .. code:: console - - $ echo "Hello" - -For text output use ``output``. - -.. code:: rst - - .. code:: output - - some output - -For text use ``text``. - -.. code:: rst - - .. code:: text - - some text - -Tables -"""""" - -We adhere to the list tables directive by docutils as described `here `__. - -A simple example would be: - - .. code:: rst - - .. list-table:: - :widths: 15 10 - :align: center - :header-rows: 1 - - * - Header 1 - - Header 2 - * - Cell 1 - - Cell 2 - * - Cell 3 - - Cell 4 - -Admonitions, messages, and warnings -""""""""""""""""""""""""""""""""""" - -`Admonitions, messages, and warnings `__ are used to draw the reader’s attention to important information, such as warnings, and for stylistic purposes. -They are typically styled as colored text boxes, usually accompanied by icons provided out of the box by Sphinx and rST. -Alerts should generally be used somewhat sparingly, so as not to cause `alert fatigue `__. - -Here are examples of several types of alerts: - -.. code:: rst - - .. hint:: - **Did you know?** The Qubes OS installer is completely offline. It doesn't - even load any networking drivers, so there is no possibility of - internet-based data leaks or attacks during the installation process. - - .. note:: - **Note:*** Using Rufus to create the installation medium means that you - `wont be able `__ - to choose the "Test this media and install Qubes OS" option mentioned in the - example below. Instead, choose the "Install Qubes OS" option. - - .. warning:: - **Note:** Qubes OS is not meant to be installed inside a virtual machine - as a guest hypervisor. In other words, **nested virtualization** is not - supported. In order for a strict compartmentalization to be enforced, Qubes - OS needs to be able to manage the hardware directly. - - .. danger:: - **Warning:** Qubes has no control over what happens on your computer - before you install it. No software can provide security if it is installed on - compromised hardware. Do not install Qubes on a computer you don't trust. See - installation security for more information. - -These render as: - -.. hint:: - **Did you know?** The Qubes OS installer is completely offline. It doesn't - even load any networking drivers, so there is no possibility of - internet-based data leaks or attacks during the installation process. - -.. note:: - **Note:** Using Rufus to create the installation medium means that you - `won't be able `__ - to choose the "Test this media and install Qubes OS" option mentioned in the - example below. Instead, choose the "Install Qubes OS" option. - -.. warning:: - **Note:** Qubes OS is not meant to be installed inside a virtual machine - as a guest hypervisor. In other words, **nested virtualization** is not - supported. In order for a strict compartmentalization to be enforced, Qubes - OS needs to be able to manage the hardware directly. - -.. danger:: - **Warning:** Qubes has no control over what happens on your computer - before you install it. No software can provide security if it is installed on - compromised hardware. Do not install Qubes on a computer you don't trust. See - installation security for more information. - -Glossary -"""""""" - -The Sphinx `glossary directive `__ -is created with a simple ``.. glossary::`` block in :file:`/user/reference/glossary.rst`. -Anywhere else in the documentation you can link to a term using the role: :code:`:term:`qube`` -which automatically generates a hyperlink to the glossary entry :term:`qube`. - -Roles -^^^^^ - -Sphinx uses interpreted text `roles `__ to insert semantic markup into documents -and thus enhance the readability and consistency of the documentation. - -Syntax is as follows: - -.. code:: rst - - :rolename:`content` - -In Qubes OS documentation the `doc `__ and -`ref `__ roles are used extensively -as described in :ref:`cross_referencing`. - -Some of the roles used in the Qubes OS documentation so far are: - -- the ``:file:`` `role `__ -- the ``:guilabel:`` `role `__ -- the ``:menuselection:`` `role `__ -- the ``:samp:`` `role `__ -- the ``:kbd:`` `role `__ - -Please continue using the above or new ones where appropriate. - -Cross referencing: -^^^^^^^^^^^^^^^^^^ - - -- Use the `:doc:` role with a path and a custom link text: - - - .. code:: rst - - :doc:`contributions `. - -<<<<<<< HEAD -use `:ref:` for specific sections -======= -- Use the `:doc:` role with a path: - - .. code:: rst ->>>>>>> origin/main - - :doc:`/introduction/intro` - -- Use `:ref:` for specific sections and a custom link text - - .. code:: rst - - - :ref:`What is Qubes OS? ` - -- Use `:ref` only with a unique label above the specific section: - - .. code:: rst - - .. _cross_referencing: - - TL;DR: Cross-referencing - ------------------------ - -and link to the section from within the documentation using :code:`:ref:`cross_referencing``. - -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 ` -* :doc:`core-admin-client ` -* :doc:`core-qrexec ` - -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 `__ 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 -^^^^^^^^^^^^^^^^ - -Use non-reference-style links like - -.. code:: rst - - `website `__ - -Do *not* use reference-style links like - -.. code:: rst - - Some text link_ - - :: _link:: https://example.org - -This facilitates the localization process. - -Take a look also at :ref:`cross_referencing`. - -Relative vs. absolute links -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Always use relative rather than absolute paths for internal website links. -For example, use: - -.. code:: rst - - text :doc:`contribute code ` text - -instead of: - -.. code:: rst - - text `contribute code ` text - -You may use absolute URLs in the following cases: - -- External links -- URLs that appear inside code blocks (e.g., in comments and document templates, and the plain text reproductions of `QSBs `__ and `Canaries `__), since they’re not hyperlinks -- Git repo files like ``README.md`` and ``CONTRIBUTING.md``, since they’re not part of the documentation itself. - -This rule is important because using absolute URLs for internal website links breaks: - -- Serving the documentation offline -- Documentation localization -- Generating offline documentation - -HTML and CSS -^^^^^^^^^^^^ - -Do not write HTML inside rST documents. In particular, never include HTML or CSS for styling, formatting, or white space control. -That belongs in the (S)CSS files instead. - -Headings -^^^^^^^^ - -Sectioning uses underlines with different characters (=, -, ^, ", ', ~) to create different levels of headings. -This is also the recommended order provided. -It doesn't matter which characters you use in which order to mark a title, subtitle etc, -as long as they are in consistent use across the documentation. - -Qubes OS uses the convention in `Python Developer’s Guide for documenting `__ which are as follows: - -.. code:: text - - # with overline, for parts - * with overline, for chapters - = for sections - - for subsections - ^ for subsubsections - " for paragraphs - -A simple example of how this is used in the Qubes OS documentation: - -.. code:: rst - - ========== - Main Title - ========== - - Subsection - ---------- - - Sub-subsection - ^^^^^^^^^^^^^^ - - Paragraph - """"""""" - -Text decorations -^^^^^^^^^^^^^^^^ - -Emphasis and Italics - -- *Italics*: Use single asterisks - - .. code:: rst - - *italics* - -- **Bold**: Use double asterisks. - - .. code:: rst - - **bold** - -- ``Monospace``: Use backticks. - - .. code:: rst - - ``monospace`` - -Paragraph -^^^^^^^^^ - -Paragraphs are plain texts where indentation matters. Separate paragraphs by leaving a blank line between them. - -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. - -Line wrapping -^^^^^^^^^^^^^ - -Do not hard wrap text, except where necessary (e.g., inside code blocks). - -Writing guidelines ------------------- - -Correct use of terminology -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Familiarize yourself with the terms defined in the :doc:`glossary `. Use these terms consistently and accurately throughout your writing. - -Sentence case in headings -^^^^^^^^^^^^^^^^^^^^^^^^^ - -Use sentence case (rather than title case) in headings for the reasons explained `here `__. In particular, since the authorship of the Qubes documentation is decentralized and widely distributed among users from around the world, many contributors come from regions with different conventions for implementing title case, not to mention that there are often differing style guide recommendations even within a single region. It is much easier for all of us to implement sentence case consistently across our growing body of pages, which is very important for managing the ongoing maintenance burden and sustainability of the documentation. - -Writing command-line examples -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -When providing command-line examples: - -- Tell the reader where to open a terminal (dom0 or a specific domU), and show the command along with its output (if any) in a code block, e.g.: - - .. code:: rst - - Open a terminal in dom0 and run: - - .. code:: console - - $ cd test - $ echo Hello - Hello - -- Precede each command with the appropriate command prompt: At a minimum, the prompt should contain a trailing ``#`` (for the user ``root``) or ``$`` (for other users) on Linux systems and ``>`` on Windows systems, respectively. - -- Don’t try to add comments inside the code block. For example, *don’t* do this: - - .. code:: rst - - Open a terminal in dom0 and run: - - .. code:: console - - # Navigate to the new directory - $ cd test - # Generate a greeting - $ echo Hello - Hello - - The ``#`` symbol preceding each comment is ambiguous with a root command prompt. Instead, put your comments *outside* of the code block in normal prose. - -Variable names in commands -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Syntactically distinguish variables in commands. For example, this is ambiguous: - -.. code:: console - - $ qvm-run --dispvm=disposable-template --service qubes.StartApp+xterm - -It should instead be: - -.. code:: console - - $ qvm-run --dispvm= --service qubes.StartApp+xterm - -Note that we syntactically distinguish variables in three ways: - -1. Surrounding them in angled brackets (``< >``) - -2. Using underscores (``_``) instead of spaces between words - -3. Using all capital letters - -We have observed that many novices make the mistake of typing the surrounding angled brackets (``< >``) on the command line, even after substituting the desired real value between them. Therefore, in documentation aimed at novices, we also recommend clarifying that the angled brackets should not be typed. This can be accomplished in one of several ways: - -- Explicitly say something like “without the angled brackets.” - -- Provide an example command using real values that excludes the angled brackets. - -- If you know that almost all users will want to use (or should use) a specific command containing all real values and no variables, you might consider providing exactly that command and forgoing the version with variables. Novices may not realize which parts of the command they can substitute with different values, but if you’ve correctly judged that they should use the command you’ve provided as is, then this shouldn’t matter. - -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 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.”) - -I have several qubes in my Qubes OS installation, and you have several in yours. Every Qubes OS user has their own set of qubes, just as each of us lives in some neighborhood on some street. Yet we aren’t tempted to treat words like “neighborhood” or “street” as proper nouns (unless, of course, they’re part of a name, like “Acorn Street”). Again, while this might seem odd because “qube” is a new word that we invented, that doesn’t change how English works. After all, *every* word was a new word that someone invented at some point (otherwise we wouldn’t have any words at all). We treat “telephone,” “computer,” “network,” “program,” and so on as common nouns, even though those were all new technological inventions in the not-too-distant past (on a historical scale, at least). So, we shouldn’t allow ourselves to be confused by irrelevant factors, like the fact that the inventors happened to be *us* or that the invention was *recent* or is not in widespread use among humanity. - -English language conventions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -For the sake of consistency and uniformity, the Qubes documentation aims to follow the conventions of American English, where applicable. (Please note that this is an arbitrary convention for the sake consistency and not a value judgment about the relative merits of British versus American English.) - -Organizational guidelines -------------------------- - -Do not duplicate documentation -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Duplicating documentation is almost always a bad idea. There are many reasons for this. The main one is that almost all documentation has to be updated as some point. When similar documentation appears in more than one place, it is very easy for it to get updated in one place but not the others (perhaps because the person updating it doesn’t realize it’s in more than once place). When this happens, the documentation as a whole is now inconsistent, and the outdated documentation becomes a trap, especially for novice users. Such traps are often more harmful than if the documentation never existed in the first place. The solution is to **link** to existing documentation rather than duplicating it. There are some exceptions to this policy (e.g., information that is certain not to change for a very long time), but they are rare. - -Core vs. external documentation -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Core documentation resides in the `Qubes OS Project’s official repositories `__, mainly in `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 `__. External documentation should not be submitted to `qubes-doc `__. If you’ve written a piece of documentation that is not appropriate for `qubes-doc `__, we encourage you to submit it to the `Qubes Forum `__ instead. However, *linking* to external documentation from `qubes-doc `__ is perfectly fine. Indeed, the maintainers of the `Qubes Forum `__ should regularly submit PRs against the documentation index (see :ref:`edit_doc_index`) to add and update Qubes Forum links in the :ref:`“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 :doc:`TemplateVM `. 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 :ref:`undergo a review process ` 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. - -On the positive side, we consider the existence of community documentation to be a sign of a healthy ecosystem, and this is quite common in the software world. The community is better positioned to write and maintain documentation that applies, combines, and simplifies the official documentation, e.g., tutorials that explain how to install and use various programs in Qubes, how to create custom VM setups, and introductory tutorials that teach basic Linux concepts and commands in the context of Qubes. In addition, just because the Qubes OS Project has officially written and maintains some flexible framework, such as ``qrexec``, it does not make sense to include every tutorial that says “here’s how to do something cool with ``qrexec`` in the core docs. Such tutorials generally also belong in the community documentation. - -See `#4693 `__ for more background information. - -Release-specific documentation -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -*See* `#5308 `__ *for pending changes to this policy.* - -We maintain only one set of documentation for Qubes OS. We do not maintain a different set of documentation for each release of Qubes. Our single set of Qubes OS documentation is updated on a continual, rolling basis. Our first priority is to document all **current, stable releases** of Qubes. Our second priority is to document the next, upcoming release (if any) that is currently in the beta or release candidate stage. - -In cases where a documentation page covers functionality that differs considerably between Qubes OS releases, the page should be subdivided into clearly-labeled sections that cover the different functionality in different releases (examples below). - -In general, avoid mentioning specific Qubes versions in the body text of documentation, as these references rapidly go out of date and become misleading to readers. - -Incorrect Example -^^^^^^^^^^^^^^^^^ - -.. code:: rst - - How to Foo - ========== - - Fooing is the process by which one foos. There are both general and specific - versions of fooing, which vary in usefulness depending on your goals, but for - the most part, all fooing is fooing. - - To foo in Qubes 3.2: - .. code:: console - $ qvm-foo - - Note that this does not work in Qubes 4.0, where there is a special widget - for fooing, which you can find in the lower-right corner of the screen in - the Foo Manager. Alternatively, you can use the more general ``qubes-baz`` - command introduced in 4.0: - .. code:: console - $ qubes-baz --foo - - Once you foo, make sure to close the baz before fooing the next bar. - -Correct Example -^^^^^^^^^^^^^^^ - -.. code:: rst - - Qubes 3.2 - ========= - - How to Foo - ---------- - - Fooing is the process by which one foos. There are both general and specific - versions of fooing, which vary in usefulness depending on your goals, but for - the most part, all fooing is fooing. - - To foo: - - .. code:: console - - $ qvm-foo - - Once you foo, make sure to close the baz before fooing the next bar. - - Qubes 4.0 - ========= - - How to Foo - ---------- - - Fooing is the process by which one foos. There are both general and specific - versions of fooing, which vary in usefulness depending on your goals, but for - the most part, all fooing is fooing. - - There is a special widget for fooing, which you can find in the lower-right - corner of the screen in the Foo Manager. Alternatively, you can use the - general ``qubes-baz`` command: - - .. code:: console - - $ qubes-baz --foo - - Once you foo, make sure to close the baz before fooing the next bar. - -Subdividing the page into clearly-labeled sections for each release has several benefits: - -- It preserves good content for older (but still supported) releases. Many documentation contributors are also people who prefer to use the latest release. Many of them are tempted to *replace* existing content that applies to an older, supported release with content that applies only to the latest release. This is somewhat understandable. Since they only use the latest release, they may be focused on their own experience, and they may even regard the older release as deprecated, even when it’s actually still supported. However, allowing this replacement of content would do a great disservice to those who still rely on the older, supported release. In many cases, these users value the stability and reliability of the older, supported release. With the older, supported release, there has been more time to fix bugs and make improvements in both the software and the documentation. Consequently, much of the documentation content for this release may have gone through several rounds of editing, review, and revision. It would be a tragedy for this content to vanish while the very set of users who most prize stability and reliability are depending on it. - -- It’s easy for readers to quickly find the information they’re looking for, since they can go directly to the section that applies to their release. - -- It’s hard for readers to miss information they need, since it’s all in one place. In the incorrect example, information that the reader needs could be in any paragraph in the entire document, and there’s no way to tell without reading the entire page. In the correct example, the reader can simply skim the headings in order to know which parts of the page need to be read and which can be safely ignored. The fact that some content is repeated in the two release-specific sections is not a problem, since no reader has to read the same thing twice. Moreover, as one release gets updated, it’s likely that the documentation for that release will also be updated. Therefore, content that is initially duplicated between release-specific sections will not necessarily stay that way, and this is a good thing: We want the documentation for a release that *doesn’t* change to stay the same, and we want the documentation for a release that *does* change to change along with the software. - -- It’s easy for documentation contributors and maintainers to know which file to edit and update, since there’s only one page for all Qubes OS releases. Initially creating the new headings and duplicating content that applies to both is only a one-time cost for each page, and many pages don’t even require this treatment, since they apply to all currently-supported Qubes OS releases. - -By contrast, an alternative approach, such as segregating the documentation into two different branches, would mean that contributions that apply to both Qubes releases would only end up in one branch, unless someone remembered to manually submit the same thing to the other branch and actually made the effort to do so. Most of the time, this wouldn’t happen. When it did, it would mean a second pull request that would have to be reviewed. Over time, the different branches would diverge in non-release-specific content. Good general content that was submitted only to one branch would effectively disappear once that release was deprecated. (Even if it were still on the website, no one would look at it, since it would explicitly be in the subdirectory of a deprecated release, and there would be a motivation to remove it from the website so that search results wouldn’t be populated with out-of-date information.) - -For further discussion about release-specific documentation in Qubes, see `here `__. - -Git conventions ---------------- - -Please follow our :ref:`Git commit message guidelines `. - -Cheatsheet: Markdown vs. reStructuredText ------------------------------------------ - -For the documentation contributors more familiar with Markdown, here is a small cheatsheet -highlighting essential differences. - -Cheatsheet: Headings -^^^^^^^^^^^^^^^^^^^^ - -**Markdown:** - - .. code:: markdown - - # Title - ## Section - ### Sub-Section - -**reStructuredText:** - - .. code:: rst - - ===== - Title - ===== - - Section - ------- - - Seub-Section - ^^^^^^^^^^^^ - -Hyperlinks -^^^^^^^^^^ - -External - -**Markdown:** - - .. code:: markdown - - [Link Text](http://example.com) - -**reStructuredText:** - - .. code:: rst - - `Link Text `__ - -Internal - -**Markdown:** - - .. code:: markdown - - [Link Text](/doc/some-file) - -**reStructuredText:** - - .. code:: rst - - :doc:`Link Text ` - -For example on cross referencing please see :ref:`cross_referencing`. - -Text Decoration -^^^^^^^^^^^^^^^ - -**Markdown:** - - .. code:: markdown - - *Italic* or _Italic_ - **Bold** or __Bold__ - ~~Strikethrough~~ - -**reStructuredText:** - - .. code:: rst - - *Italic* - **Bold** - :strike:`Strikethrough` - -Cheatsheet: Lists -^^^^^^^^^^^^^^^^^ - -**Markdown:** - - .. code:: markdown - - - Item 1 - - Item 2 - - Subitem 1 - - Subitem 2 - - 1. Item 1 - 2. Item 2 - a. Subitem 1 - b. Subitem 2 - -**reStructuredText:** - - .. code:: rst - - - Item 1 - - Item 2 - - Subitem 1 - - Subitem 2 - - 1. Item 1 - 2. Item 2 - a. Subitem 1 - b. Subitem 2 - -Cheatsheet: Tables -^^^^^^^^^^^^^^^^^^ - -**Markdown:** - - .. code:: markdown - - | Header 1 | Header 2 | - |----------|----------| - | Cell 1 | Cell 2 | - | Cell 3 | Cell 4 | - -**reStructuredText:** - - .. code:: rst - - .. list-table:: rst - :widths: 15 10 - :align: center - :header-rows: 1 - - * - Header 1 - - Header 2 - * - Cell 1 - - Cell 2 - * - Cell 3 - - Cell 4 - -Cheatsheet: Code Blocks -^^^^^^^^^^^^^^^^^^^^^^^ - -**Markdown:** - .. code:: markdown - - ```python - print("Hello, world!") - ``` - -**reStructuredText:** - - .. code:: rst - - .. code:: python - - print("Hello, world!") - -Alerts and Warnings -^^^^^^^^^^^^^^^^^^^ - -**Markdown:** - -Markdown does not have built-in support for alerts and warnings. - -**reStructuredText:** - - .. code:: rst - - .. note:: - - This is a note. - - .. warning:: - - This is a warning. - - .. danger:: - - This is a danger message. diff --git a/index.rst b/index.rst index 3823f53c..e8fd989a 100644 --- a/index.rst +++ b/index.rst @@ -2,8 +2,6 @@ Documentation ============= -:doc:`core-admin:index` - ================= Table of contents =================