mirror of
https://github.com/QubesOS/qubes-doc.git
synced 2025-10-13 02:50:36 -04:00
fix references, refactor website style doc and others
This commit is contained in:
qubedmaiska
parent
bd26dee6a4
commit
0bf898475f
5 changed files with 111 additions and 222 deletions
|
|
@ -4,9 +4,11 @@ How to edit the documentation
|
|||
|
||||
The Qubes OS documentation is stored as `reStructuredText (rST) <https://docutils.sourceforge.io/rst.html>`__ files in
|
||||
the `qubes-doc <https://github.com/QubesOS/qubes-doc>`__ repository.
|
||||
|
||||
We use `Sphinx <https://www.sphinx-doc.org/>`__ for building and
|
||||
`Read The Docs (RTD) <https://readsthedocs.com/>`__ for hosting.
|
||||
RTD is a `continuous‑documentation deployment platform <https://docs.readthedocs.com/platform/stable/continuous-deployment.html>`__ that automatically detects changes in the qubes-doc GittHub repository and builds the latest version of the docs.
|
||||
RTD is a `continuous‑documentation deployment platform <https://docs.readthedocs.com/platform/stable/continuous-deployment.html>`__ that can automatically
|
||||
detect changes in a GitHub repository and build the latest version of a documentation.
|
||||
|
||||
.. figure:: /attachment/doc/rst-rtd-workflow.png
|
||||
:alt: Qubes OS Documentation Workflow - once new documentation is written or changed, it is built and verified with Sphinx, pushed on GitHub/GitLab and hosted on RTD
|
||||
|
|
@ -16,7 +18,8 @@ RTD is a `continuous‑documentation deployment platform <https://docs.readthedo
|
|||
|
||||
By cloning and regularly pulling from `qubes-doc <https://github.com/QubesOS/qubes-doc>`__ repository, users can maintain their
|
||||
own up-to-date offline copy of the Qubes documentation rather than
|
||||
relying solely on the web. EPUB or PDF versions of Qubes OS documenation can also
|
||||
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
|
||||
be downloaded from `doc.qubes-os.org <https://doc.qubes-os.org/en/latest/>`__:
|
||||
|
||||
|epub-pdf|
|
||||
|
|
@ -25,6 +28,8 @@ be downloaded from `doc.qubes-os.org <https://doc.qubes-os.org/en/latest/>`__:
|
|||
TODO screenshots with main branch instead of rst when rst merged in main
|
||||
TODO add draft pull request screenshot
|
||||
|
||||
|
||||
|
||||
The documentation is a volunteer community effort. People like you are
|
||||
constantly working to make it better. If you notice something that can
|
||||
be fixed or improved, please follow the steps below to open a pull
|
||||
|
|
@ -56,16 +61,17 @@ A few notes before we get started:
|
|||
work from the command line, you can skip the rest of this section. All
|
||||
you need to do to contribute is to `fork and clone <https://guides.github.com/activities/forking/>`__
|
||||
the `qubes-doc <https://github.com/QubesOS/qubes-doc>`__ repo, make your changes,
|
||||
then `submit a pull request <https://help.github.com/articles/using-pull-requests/>`__.)
|
||||
then `submit a pull request <https://help.github.com/articles/using-pull-requests/>`__.
|
||||
You can continue reading :ref:`viewing_pr`.)
|
||||
|
||||
Ok, let’s begin. Every documentation page has a “Edit on GitHub” link.
|
||||
Ok, let’s begin. Every documentation page has a :guilabel:`Edit on GitHub` link.
|
||||
|
||||
|page-source-button|
|
||||
|
||||
When you click on it, you’ll be taken to the source file — a reStructuredText (``.rst``) file — on GitHub.
|
||||
|
||||
On this page, there will be a
|
||||
button to edit the file (if you are already logged in in).
|
||||
button to edit the file (if you are already logged in).
|
||||
|
||||
..
|
||||
TODO screenshot when rst merged in main
|
||||
|
|
@ -79,12 +85,12 @@ You can also create a free account from here.
|
|||
|github-sign-in|
|
||||
|
||||
If this is your first contribution to the documentation, you need to
|
||||
:guilabel:`fork` the repository (make your own copy).
|
||||
fork the repository (make your own copy).
|
||||
|
||||
|fork1|
|
||||
|
||||
It’s easy — just click the
|
||||
green :guilabel:`Create fork` on the next page. This step is only needed the first
|
||||
green :guilabel:`Create fork` button on the next page. This step is only needed the first
|
||||
time you make a contribution.
|
||||
|
||||
|
||||
|
|
@ -94,15 +100,14 @@ Now you can make your modifications.
|
|||
|
||||
|fork3|
|
||||
|
||||
You can also preview the changes by clicking the :guilabel:`Preview changes` tab.
|
||||
|
||||
If you want to add images, read :ref:`how_to_add_images`.
|
||||
and refer to :ref:`build_locally`
|
||||
if you want to locally verify that everything looks correct before submitting any changes.
|
||||
.. You can also preview the changes by clicking the :guilabel:`Preview changes` tab.
|
||||
|
||||
|
||||
|edit|
|
||||
|
||||
If you want to add images, read :ref:`how_to_add_images` and refer to :ref:`build_locally`
|
||||
if you want to locally verify that everything looks correct before submitting any changes.
|
||||
|
||||
|
||||
Once you’re finished, describe your changes at the bottom and click
|
||||
:guilabel:`Commit changes`.
|
||||
|
|
@ -110,8 +115,8 @@ Once you’re finished, describe your changes at the bottom and click
|
|||
|commit|
|
||||
|
||||
After that, you’ll see exactly what modifications you’ve made. At this
|
||||
stage, those changes are still in your own copy of the documentation
|
||||
(“fork”). If everything looks good, send those changes to us by pressing
|
||||
stage, those changes are still in your own copy (fork) of the documentation.
|
||||
If everything looks good, send those changes to us by pressing
|
||||
the :guilabel:`Create pull request` button.
|
||||
|
||||
|
||||
|
|
@ -135,11 +140,14 @@ can’t accept your pull request, we’ll post a comment explaining why we
|
|||
can’t.
|
||||
|
||||
|
||||
.. _viewing_pr:
|
||||
|
||||
Viewing your pull request on RTD
|
||||
--------------------------------
|
||||
|
||||
Every time you push a commit to your pull request, a build on RTD will be triggered.
|
||||
To view your PR you can go to Qubes OS builds on `RTD <https://app.readthedocs.org/projects/qubes-doc/builds/>`__:
|
||||
To view your PR you can go to Qubes OS builds on `RTD <https://app.readthedocs.org/projects/qubes-doc/builds/>`__,
|
||||
find the last build of your PR and click on it:
|
||||
|
||||
|pull-request-builds|
|
||||
|
||||
|
|
@ -198,14 +206,11 @@ If you want to add a newly created documentation file, do so as follows:
|
|||
.. code-block:: rst
|
||||
|
||||
.. toctree:
|
||||
old_doc_file_name
|
||||
new_doc_file_name
|
||||
/path/to/old_doc_file_name
|
||||
/path/to/new_doc_file_name
|
||||
|
||||
|
||||
Editing this file will change what appears on the documentation index.
|
||||
If your pull request (PR) adds, removes, or edits anything that should
|
||||
be reflected in the documentation index, please make sure you also
|
||||
submit an associated pull request against this file.
|
||||
|
||||
Please always be mindful that rST syntax is sensitive to indentation (3 spaces)!
|
||||
|
||||
|
|
@ -226,7 +231,7 @@ To add an image to a page, use the following syntax:
|
|||
:alt: Qubes desktop screenshot depicting <description>
|
||||
|
||||
|
||||
If you want to add a caption to the image, you may do so using the ``caption`` option of the `figure directive <https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure>`__.
|
||||
If you want to add a caption to the image, you may do so using the optional ``caption`` of the `figure directive <https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure>`__.
|
||||
Another way without a caption is to use the `image directive <https://docutils.sourceforge.io/docs/ref/rst/directives.html#image>`__.
|
||||
|
||||
Then, add your image(s) in a the :file:`attachment/doc` folder in the `qubes-doc <https://github.com/QubesOS/qubes-doc>`__
|
||||
|
|
@ -272,6 +277,27 @@ which will refer to :ref:`this section <introduction/faq:what does it mean to "d
|
|||
For further options and use cases please refer to `Cross-references <https://www.sphinx-doc.org/en/master/usage/referencing.html>`__.
|
||||
|
||||
|
||||
Qubes OS rST configuration
|
||||
==========================
|
||||
|
||||
:file:`qubes-doc` directory contains a build configuration file named :file:`conf.py`, used by Sphinx
|
||||
to define `input and output behaviour <https://www.sphinx-doc.org/en/master/usage/configuration.html>`__.
|
||||
It contains settings and extensions that define how the documentation will be generated.
|
||||
You can find it `here <https://github.com/QubesOS/qubes-doc/blob/rst/conf.py>`__.
|
||||
|
||||
You can also find a :file:`readthedocs.yml` `file <https://github.com/QubesOS/qubes-doc/blob/rst/.readthedocs.yaml>`__
|
||||
which tells RTD how to build the documentation. It defines the build environment, Python version, required dependencies,
|
||||
and which Sphinx configuration to run. Thus RTD automatically generates and hosts the docs.
|
||||
|
||||
|
||||
Extensions
|
||||
----------
|
||||
|
||||
We use several Sphinx `extensions <https://www.sphinx-doc.org/en/master/usage/extensions/index.html>`__
|
||||
as defined in :file:`conf.py`, as well a simple custom one to embed YouTube videos,
|
||||
which can be found `here <https://github.com/QubesOS/qubes-doc/tree/rst/_ext>`__.
|
||||
|
||||
|
||||
.. _build_locally:
|
||||
|
||||
Building the rST documentation locally
|
||||
|
|
@ -282,7 +308,9 @@ In order to build the Qubes OS rST documentation locally clone the `qubes-doc <h
|
|||
(or your forked one if you want to submit a pull request).
|
||||
|
||||
|
||||
It is recommended to use a virtual environment, f.ex. venv or uv poetry.
|
||||
It is recommended to use a virtual environment, f.ex.
|
||||
`venv <https://docs.python.org/3/library/venv.html>`__,
|
||||
`poetry <https://python-poetry.org/>`__ or `uv <https://docs.astral.sh/uv/>`__.
|
||||
In the following section there is a sample setup to prepare local environments
|
||||
for building Qubes OS rST documentation.
|
||||
|
||||
|
|
@ -428,7 +456,7 @@ A :file:`pyproject.toml` file is provided.
|
|||
$ poetry run sphinx-autobuild ../qubes-doc _build/html
|
||||
|
||||
|
||||
You can also use `uv <https://docs.astral.sh/uv/getting-started/>`__ as you wish.
|
||||
You can also use `uv <https://docs.astral.sh/uv/getting-started/>`__ if you wish.
|
||||
|
||||
|
||||
Editor
|
||||
|
|
@ -445,32 +473,10 @@ An editor you can use is `ReText <https://github.com/retext-project/retext>`__ b
|
|||
$ pip3 install ReText
|
||||
|
||||
|
||||
Configuration
|
||||
-------------
|
||||
|
||||
Qubes-doc directory contains a build configuration file named :file:`conf.py`, used by Sphinx
|
||||
to define `input and output behaviour <https://www.sphinx-doc.org/en/master/usage/configuration.html>`__.
|
||||
It contains settings and extensions that define how the documentation will be generated.
|
||||
|
||||
You can find it `here <https://github.com/QubesOS/qubes-doc/blob/rst/conf.py>`__.
|
||||
|
||||
You can also find a :file:`readthedocs.yml` `file <https://github.com/QubesOS/qubes-doc/blob/rst/.readthedocs.yaml>`__
|
||||
which tells RTD how to build the documentation. It defines the build environment, Python version, required dependencies,
|
||||
and which Sphinx configuration to run. Thus RTD automatically generates and hosts the docs.
|
||||
|
||||
|
||||
Extensions
|
||||
----------
|
||||
|
||||
We use several Sphinx `extensions <https://www.sphinx-doc.org/en/master/usage/extensions/index.html>`__
|
||||
as defined in :file:`conf.py`, as well a simple custom one to embed YouTube videos,
|
||||
which can be found `here <https://github.com/QubesOS/qubes-doc/tree/rst/_ext>`__.
|
||||
|
||||
|
||||
Security
|
||||
========
|
||||
|
||||
Also see: :ref:`FAQ: Why is the documentation hosted on ReadTheDocs as opposed to the website? <introduction/faq:why is the documentation hosted on readthedocs as opposed to the website?>`.
|
||||
Also see: :ref:`FAQ: Why is the documentation hosted on ReadTheDocs as opposed to the website? <introduction/faq:why is the documentation hosted on readthedocs as opposed to the website?>`
|
||||
|
||||
All pull requests (PRs) against `qubes-doc <https://github.com/QubesOS/qubes-doc>`__ must pass review
|
||||
prior to be merged, except in the case of :ref:`external documentation <index:external documentation>`
|
||||
|
|
@ -533,3 +539,5 @@ you are not willing or able to do so.)
|
|||
:alt: Highlights the View Docs button in a specific build for a pull request <number> on RTD
|
||||
.. |epub-pdf| image:: /attachment/doc/rst-rtd-epub-pdf.png
|
||||
:alt: Highlights from where one can download a ePUB or PDF of hte Qubes OS documentation deployed on RTD
|
||||
:scale: 20 %
|
||||
:align: middle
|
||||
|
|
|
|||
|
|
@ -69,11 +69,10 @@ Quick intro to Jekyll
|
|||
|
||||
- *Reading data*: YAML front‑matter in :file:`pages/_posts` and files under :file:`_data` give variables you can reuse.
|
||||
- *Applying layouts*: HTML layout files wrap your content, letting you keep a consistent header/footer, navigation, etc.
|
||||
- *Processing includes*: Reusable snippets (HTML/Jinja‑style) can be dropped into pages.
|
||||
- *Processing includes*: Reusable snippets (HTML/`Liquid <https://jekyllrb.com/docs/liquid/>`__) can be dropped into pages.
|
||||
- *Compiling assets*: SASS/SCSS files become CSS, JavaScript is copied as‑is.
|
||||
- *Generating the output*: All source files are rendered into a :file:`_site` folder that contains the ready‑to‑serve static files.
|
||||
|
||||
|
||||
The main `qubesos.github.io <https://github.com/QubesOS/qubesos.github.io>`__ contains the following directories:
|
||||
|
||||
.. code:: bash
|
||||
|
|
@ -87,7 +86,7 @@ The main `qubesos.github.io <https://github.com/QubesOS/qubesos.github.io>`__ co
|
|||
├── _hcl # ← “qubes‑hcl” submodule – custom content for HCL pages
|
||||
│ └── ... #
|
||||
│
|
||||
├── _includes # ← Reusable HTML/Jinja snippets
|
||||
├── _includes # ← Reusable HTML/Liquid snippets
|
||||
│ └── *.html # include with {% include filename.html %} in Markdown or layouts
|
||||
│
|
||||
├── _layouts # ← Page templates that wrap content
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ reStructuredText documentation style guide
|
|||
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 <https://doc.qubes-os.org>`__),
|
||||
please see the :doc:`website style guide </developer/general/website-style-guide>`.
|
||||
please see the :doc:`Website style guide </developer/general/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 </developer/general/how-to-edit-the-website/>`.
|
||||
|
||||
|
|
@ -91,8 +91,8 @@ Item 3 will start at 1.
|
|||
Code blocks
|
||||
"""""""""""
|
||||
|
||||
When writing code blocks, use syntax highlighting within the `code-block <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block>`__
|
||||
or `code <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code>`__.
|
||||
When writing code blocks, use syntax highlighting within the `code <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code>`__
|
||||
or `code-block <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block>`__.
|
||||
|
||||
By specifying the language, you enable pygments, which show syntax color coding for that code sample (see `here <https://pygments.org/languages/>`__ for a list of supported languages).
|
||||
|
||||
|
|
@ -146,7 +146,7 @@ For Bash use ``bash``.
|
|||
|
||||
.. code:: bash
|
||||
|
||||
echo "Hello"
|
||||
#!/bin/bash
|
||||
|
||||
For a terminal session use ``console``.
|
||||
|
||||
|
|
@ -154,7 +154,7 @@ For a terminal session use ``console``.
|
|||
|
||||
.. code:: console
|
||||
|
||||
pygments_style = 'sphinx'
|
||||
$ echo "Hello"
|
||||
|
||||
For text output use ``output``.
|
||||
|
||||
|
|
@ -182,8 +182,9 @@ A simple example would be:
|
|||
|
||||
.. code:: rst
|
||||
|
||||
.. list-table:: rst
|
||||
.. list-table::
|
||||
:widths: 15 10
|
||||
:align: center
|
||||
:header-rows: 1
|
||||
|
||||
* - Header 1
|
||||
|
|
@ -280,17 +281,17 @@ In Qubes OS documentation the `doc <https://www.sphinx-doc.org/en/master/usage/r
|
|||
`ref <https://www.sphinx-doc.org/en/master/usage/referencing.html#role-ref>`__ roles are used extensively
|
||||
as described in :ref:`cross_referencing`.
|
||||
|
||||
The roles used in the Qubes OS documentation so far are:
|
||||
Some of the roles used in the Qubes OS documentation so far are:
|
||||
|
||||
- the ``:file:`` `role <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-file>`__
|
||||
- the ``:guilabel:`` `role <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-guilabel>`__
|
||||
- the ``:menuselection:`` `role <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-menuselection>`__
|
||||
- the ``:samp:`` `role <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-samp>`__
|
||||
- the ``:kbd:`` `role <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-kbd>`__
|
||||
|
||||
Please continue using the above or new ones where appropriate.
|
||||
|
||||
|
||||
|
||||
Cross referencing:
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
|
@ -308,7 +309,7 @@ use `:ref:` for specific sections
|
|||
:ref:`qubes <user/reference/glossary:qube>`
|
||||
|
||||
|
||||
For further information please :ref:`cross_referencing`.
|
||||
For further information please see :ref:`cross_referencing`.
|
||||
|
||||
|
||||
Hyperlink syntax
|
||||
|
|
@ -331,7 +332,7 @@ Do *not* use reference-style links like
|
|||
|
||||
This facilitates the localization process.
|
||||
|
||||
Take a look also :ref:`cross_referencing`.
|
||||
Take a look also at :ref:`cross_referencing`.
|
||||
|
||||
|
||||
Relative vs. absolute links
|
||||
|
|
@ -348,7 +349,7 @@ instead of:
|
|||
|
||||
.. code:: rst
|
||||
|
||||
text :doc:`contribute code </introduction/contributing>` text
|
||||
text `contribute code <https://doc.qubes-os.org/introduction/contributing.html>` text
|
||||
|
||||
You may use absolute URLs in the following cases:
|
||||
|
||||
|
|
@ -383,7 +384,8 @@ as long as they are in consistent use across the documentation.
|
|||
Qubes OS uses the convention in `Python Developer’s Guide for documenting <https://devguide.python.org/documentation/markup/#sections>`__ which are as follows:
|
||||
|
||||
|
||||
.. code: text
|
||||
.. code:: text
|
||||
|
||||
# with overline, for parts
|
||||
* with overline, for chapters
|
||||
= for sections
|
||||
|
|
@ -391,17 +393,19 @@ Qubes OS uses the convention in `Python Developer’s Guide for documenting <htt
|
|||
^ 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
|
||||
"""""""""
|
||||
|
|
@ -475,7 +479,9 @@ When providing command-line examples:
|
|||
.. code:: rst
|
||||
|
||||
Open a terminal in dom0 and run:
|
||||
|
||||
.. code:: console
|
||||
|
||||
$ cd test
|
||||
$ echo Hello
|
||||
Hello
|
||||
|
|
@ -488,7 +494,9 @@ When providing command-line examples:
|
|||
.. code:: rst
|
||||
|
||||
Open a terminal in dom0 and run:
|
||||
|
||||
.. code:: console
|
||||
|
||||
# Navigate to the new directory
|
||||
$ cd test
|
||||
# Generate a greeting
|
||||
|
|
@ -694,6 +702,9 @@ Please follow our :ref:`Git commit message guidelines <developer/code/coding-sty
|
|||
Cheatsheet: Markdown vs. reStructuredText
|
||||
-----------------------------------------
|
||||
|
||||
For the documentation contributors more familiar with Markdown, here is a small cheatsheet
|
||||
highlighting essential differences.
|
||||
|
||||
Headings
|
||||
^^^^^^^^
|
||||
|
||||
|
|
@ -701,23 +712,23 @@ Headings
|
|||
|
||||
.. code:: markdown
|
||||
|
||||
# Heading 1
|
||||
## Heading 2
|
||||
### Heading 3
|
||||
# Title
|
||||
## Section
|
||||
### Sub-Section
|
||||
|
||||
**reStructuredText:**
|
||||
|
||||
.. code:: rst
|
||||
|
||||
============
|
||||
Heading 1
|
||||
============
|
||||
=====
|
||||
Title
|
||||
=====
|
||||
|
||||
Heading 2
|
||||
----------
|
||||
Section
|
||||
-------
|
||||
|
||||
Heading 3
|
||||
^^^^^^^^^
|
||||
Seub-Section
|
||||
^^^^^^^^^^^^
|
||||
|
||||
Hyperlinks
|
||||
^^^^^^^^^^
|
||||
|
|
@ -816,10 +827,12 @@ Tables
|
|||
| Cell 3 | Cell 4 |
|
||||
|
||||
**reStructuredText:**
|
||||
|
||||
.. code:: rst
|
||||
|
||||
.. list-table:: rst
|
||||
:widths: 15 10
|
||||
:align: center
|
||||
:header-rows: 1
|
||||
|
||||
* - Header 1
|
||||
|
|
@ -855,13 +868,17 @@ Alerts and Warnings
|
|||
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.
|
||||
|
|
|
|||
|
|
@ -62,14 +62,9 @@ Markdown style guide and conventions
|
|||
------------------------------------
|
||||
|
||||
|
||||
*Also see* :doc:`how to edit the website </developer/general/how-to-edit-the-website>`.
|
||||
*Also see* :doc:`How to edit the website </developer/general/how-to-edit-the-website>`.
|
||||
|
||||
Some of the Qubes OS website pages are stored as plain text Markdown files in the `qubesos.github.io <https://github.com/QubesOS/qubesos.github.io>`__ repository.
|
||||
|
||||
|
||||
Markdown conventions
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
When making contributions to Markdown files, please observe the following style conventions. If you’re not familiar with Markdown syntax, `this <https://daringfireball.net/projects/markdown/>`__ is a great resource.
|
||||
|
||||
Hyperlink syntax
|
||||
|
|
@ -148,7 +143,7 @@ Do not use Markdown syntax for styling
|
|||
|
||||
For example, there is a common temptation to use block quotations (created by beginning lines with the ``>`` character) in order to stylistically distinguish some portion of text from the rest of the document, e.g.:
|
||||
|
||||
.. code:: bash
|
||||
.. code:: markdown
|
||||
|
||||
> **Note:** This is an important note!
|
||||
|
||||
|
|
@ -168,7 +163,7 @@ There are two problems with this:
|
|||
|
||||
Instead, an example of an appropriate way to stylistically distinguish a portion of text is by using `alerts <#alerts>`__. Consider also that extra styling and visual distinction may not even be necessary. In most cases, traditional writing methods are perfectly sufficient, e.g.,:
|
||||
|
||||
.. code:: bash
|
||||
.. code:: markdown
|
||||
|
||||
**Note:** This is an important note.
|
||||
|
||||
|
|
@ -225,15 +220,8 @@ These render as:
|
|||
Writing guidelines
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Correct use of terminology
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Familiarize yourself with the terms defined in the :doc:`glossary </user/reference/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 <https://www.sallybagshaw.com.au/articles/sentence-case-v-title-case/>`__. 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.
|
||||
For writing guidelines please refer to the :ref:`appropriate section <developer/general/rst-documentation-style-guide:writing guidelines>` in the rST documentation style guide
|
||||
with the exemption of the following:
|
||||
|
||||
Writing command-line examples
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
|
@ -242,7 +230,7 @@ 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:: bash
|
||||
.. code:: markdown
|
||||
|
||||
Open a terminal in dom0 and run:
|
||||
```
|
||||
|
|
@ -254,7 +242,7 @@ When providing command-line examples:
|
|||
- 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:: bash
|
||||
.. code:: markdown
|
||||
|
||||
Open a terminal in dom0 and run:
|
||||
```
|
||||
|
|
@ -268,129 +256,6 @@ 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:: bash
|
||||
|
||||
$ qvm-run --dispvm=disposable-template --service qubes.StartApp+xterm
|
||||
|
||||
It should instead be:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
$ qvm-run --dispvm=<DISPOSABLE_TEMPLATE> --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 orthographicallly 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.)
|
||||
|
||||
|
||||
Incorrect Example
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. code:: bash
|
||||
|
||||
## 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:
|
||||
|
||||
$ qvm-foo <foo-bar>
|
||||
|
||||
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:
|
||||
|
||||
$ qubes-baz --foo <bar>
|
||||
|
||||
Once you foo, make sure to close the baz before fooing the next bar.
|
||||
|
||||
|
||||
Correct Example
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
.. code:: bash
|
||||
|
||||
## 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:
|
||||
|
||||
$ qvm-foo <foo-bar>
|
||||
|
||||
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:
|
||||
|
||||
$ qubes-baz --foo <bar>
|
||||
|
||||
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 <https://groups.google.com/d/topic/qubes-users/H9BZX4K9Ptk/discussion>`__.
|
||||
|
||||
Git conventions
|
||||
---------------
|
||||
|
||||
|
|
|
|||
|
|
@ -320,7 +320,7 @@ Should I trust this website?
|
|||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
This website is hosted on `GitHub Pages <https://pages.github.com/>`__ (`why? <#why-do-you-use-github>`__). Therefore, it is largely outside of our control. We don’t consider this a problem, however, since we explicitly `distrust the infrastructure <#what-does-it-mean-to-distrust-the-infrastructure>`__. For this reason, we don’t think that anyone should place undue trust in the live version of this site on the Web. Instead, if you want to obtain your own trustworthy copy of this website in a secure way, you should clone our `website repo <https://github.com/QubesOS/qubesos.github.io>`__, :ref:`verify the PGP signatures on the commits and/or tags <project-security/verifying-signatures:how to verify signatures on git repository tags and commits>` signed by the `doc-signing keys <https://github.com/QubesOS/qubes-secpack/tree/master/keys/doc-signing>`__ (which indicates that the content has undergone :ref:`review <developer/general/how-to-edit-the-website:security>`), then either `render the site on your local machine <https://github.com/QubesOS/qubesos.github.io/blob/master/README.md#instructions>`__ or simply read the source, the vast majority of which was :ref:`intentionally written in Markdown so as to be readable as plain text for this very reason <developer/general/website-style-guide:markdown conventions>`. We’ve gone to special effort to set all of this up so that no one has to trust the infrastructure and so that the contents of this website are maximally available and accessible.
|
||||
This website is hosted on `GitHub Pages <https://pages.github.com/>`__ (`why? <#why-do-you-use-github>`__). Therefore, it is largely outside of our control. We don’t consider this a problem, however, since we explicitly `distrust the infrastructure <#what-does-it-mean-to-distrust-the-infrastructure>`__. For this reason, we don’t think that anyone should place undue trust in the live version of this site on the Web. Instead, if you want to obtain your own trustworthy copy of this website in a secure way, you should clone our `website repo <https://github.com/QubesOS/qubesos.github.io>`__, :ref:`verify the PGP signatures on the commits and/or tags <project-security/verifying-signatures:how to verify signatures on git repository tags and commits>` signed by the `doc-signing keys <https://github.com/QubesOS/qubes-secpack/tree/master/keys/doc-signing>`__ (which indicates that the content has undergone :ref:`review <developer/general/how-to-edit-the-website:security>`), then either `render the site on your local machine <https://github.com/QubesOS/qubesos.github.io/blob/master/README.md#instructions>`__ or simply read the source, the vast majority of which was :ref:`intentionally written in Markdown so as to be readable as plain text for this very reason <developer/general/website-style-guide:markdown style guide and conventions>`. We’ve gone to special effort to set all of this up so that no one has to trust the infrastructure and so that the contents of this website are maximally available and accessible.
|
||||
|
||||
|
||||
What does it mean to "distrust the infrastructure"?
|
||||
|
|
@ -561,7 +561,7 @@ or
|
|||
|
||||
- Go to the sysfs (``/sys/bus/pci``), find the right device, detach it from the pciback driver and attach back to the original driver. Replace ``<BDF>`` with your device, for example ``00:1c.2``:
|
||||
|
||||
.. code:: bash
|
||||
.. code:: console
|
||||
|
||||
$ echo 0000:<BDF> > /sys/bus/pci/drivers/pciback/unbind
|
||||
$ MODALIAS=`cat /sys/bus/pci/devices/0000:<BDF>/modalias`
|
||||
|
|
@ -588,7 +588,7 @@ For Debian:
|
|||
|
||||
|
||||
|
||||
.. code:: bash
|
||||
.. code:: console
|
||||
|
||||
$ sudo apt install vlc
|
||||
|
||||
|
|
@ -607,7 +607,7 @@ For Fedora:
|
|||
|
||||
|
||||
|
||||
.. code:: bash
|
||||
.. code:: console
|
||||
|
||||
$ sudo dnf install vlc
|
||||
|
||||
|
|
@ -690,7 +690,7 @@ I see a screen popup with SeaBios and 4 lines, last one being ``Probing EDD (edd
|
|||
|
||||
From a ``dom0`` prompt, enter:
|
||||
|
||||
.. code:: bash
|
||||
.. code:: console
|
||||
|
||||
$ qvm-prefs <HVMname> kernel ""
|
||||
|
||||
|
|
@ -714,7 +714,7 @@ I see a "Failed to start Load Kernel Modules" message on boot
|
|||
|
||||
The full message looks like:
|
||||
|
||||
.. code:: bash
|
||||
.. code:: output
|
||||
|
||||
[FAILED] Failed to start Load Kernel Modules.
|
||||
See 'systemctl status systemd-modules-load.service' for details.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue