Add initial How to edit the rst documentation and rst documentaion style guide docs

introduction/faq.rst

@@ -250,7 +250,6 @@ Here is an overview of the VM virtualization modes:
      - PV
 
 
-
 What's so special about Qubes' GUI virtualization?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -285,7 +284,8 @@ How should I report documentation issues?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 
-If you can fix the problem yourself, please see `how to edit the documentation <https://www.qubes-os.org/doc/how-to-edit-the-documentation/>`__. If not, please see :doc:`issue tracking </introduction/issue-tracking>`.
+If you can fix the problem yourself, please see :doc:`how to edit the documentation </developer/general/how-to-edit-the-rst-documentation/>`.
+If not, please see :doc:`issue tracking </introduction/issue-tracking>`.
 
 Will Qubes seek to get certified under the GNU Free System Distribution Guidelines (GNU FSDG)?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -299,12 +299,30 @@ The `four essential freedoms <https://www.gnu.org/philosophy/free-sw.html>`__ ar
 
 Also see `Is Qubes OS free and open-source software? <#is-qubes-os-free-and-open-source-software>`__ and the Qubes OS :doc:`software license </developer/code/license>`.
 
+Why is the documentation hosted on ReadTheDocs as opposed to the website?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The Qubes OS documentation is written in reStructuredText and hosted on `Read The Docs <https://readsthedocs.com/>`__.
+The infrastructure 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 the documentation in a secure way,
+you should clone our `documentation repo <https://github.com/QubesOS/qubes-doc>`__,
+: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-rst-documentation:security>`),
+then either :ref:`render the documentation on your local machine <developer/general/how-to-edit-the-rst-documentation:building the rst documentation locally>`,
+simply read the source, or download a rendered EPUB or PDF Version from `doc.qubes-os.org <https://doc.qubes-os.org/en/latest/>`__.
+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 the documentaion are maximally available and accessible.
+
+
+
 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 `review <https://www.qubes-os.org/doc/how-to-edit-the-documentation/#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 `intentionally written in Markdown so as to be readable as plain text for this very reason <https://www.qubes-os.org/doc/documentation-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.
 
+
 What does it mean to "distrust the infrastructure"?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -543,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:: console
+  .. code:: bash
 
         echo 0000:<BDF> > /sys/bus/pci/drivers/pciback/unbind
         MODALIAS=`cat /sys/bus/pci/devices/0000:<BDF>/modalias`
@@ -570,7 +588,7 @@ For Debian:
 
 
 
-   .. code:: console
+   .. code:: bash
 
          $ sudo apt install vlc
 
@@ -589,7 +607,7 @@ For Fedora:
 
 
 
-   .. code:: console
+   .. code:: bash
 
          $ sudo dnf install vlc
 
@@ -672,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:: console
+.. code:: bash
 
       qvm-prefs <HVMname> kernel ""
 
@@ -696,7 +714,7 @@ I see a "Failed to start Load Kernel Modules" message on boot
 
 The full message looks like:
 
-.. code:: text
+.. code:: bash
 
       [FAILED] Failed to start Load Kernel Modules.
       See 'systemctl status systemd-modules-load.service' for details.

introduction/intro.rst

@@ -71,7 +71,7 @@ Why Qubes OS?
 
 
 Physical isolation is a given safeguard that the digital world lacks
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Throughout our lives, we engage in various activities, such as going to
 school, working, voting, taking care of our families, and visiting with
@@ -159,20 +159,20 @@ open-source in order to be trustworthy.
 
 
 Video Tours
-~~~~~~~~~~~
+^^^^^^^^^^^
 
 Want to see Qubes OS in action? Sit back and watch a guided :doc:`tour! </introduction/video-tours/>`
 
 
 Screenshots
-~~~~~~~~~~~
+^^^^^^^^^^^
 
 See what using Qubes actually looks like with these :doc:`screenshots </introduction/screenshots/>` of various
 applications running in Qubes.
 
 
 Getting Started
-~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^
 
 Ready to get started with Qubes? :doc:`Here's </introduction/getting-started>` what you need to know after installing.
 

introduction/privacy.rst

@@ -11,7 +11,26 @@ Website
 
 For the legally-required boilerplate, see `Website Privacy Policy <https://www.qubes-os.org/website-privacy-policy/>`__.
 
-This is just a static website generated with Jekyll and hosted from GitHub Pages. We try to use as little JavaScript as possible. We host all resources locally (no third-party CDNs) so that you only have to connect to one domain. This site should be easy to browse using Tor Browser and with scripts blocked. We also have an `onion service <http://qubesosfasa4zl44o4tws22di6kepyzfeqv3tg4e3ztknltfxqrymdad.onion/>`__ (access is not logged). We even go out of our way to make it easy to download `this website’s git repo <https://github.com/QubesOS/qubesos.github.io>`__, including all the website source code, so that you can host this entire site from your own local machine offline. Better yet, we’ve specifically written all of the :doc:`documentation </index>` in Markdown so that the plain text can be enjoyed from the comfort of your terminal. Here’s the `repo <https://github.com/QubesOS/qubes-doc>`__. (By the way, Git tags on our repos are PGP-signed so you can :doc:`verify </project-security/verifying-signatures>` the authenticity of the content.) Obviously, we don’t use any ads or trackers, but this is still a public website, so man-in-the-middle attacks and such are always a possibility. Please be careful. See :ref:`FAQ: Should I trust this website? <introduction/faq:should i trust this website?>`
+This is just a static website generated with Jekyll and hosted from GitHub Pages. We try to use as little JavaScript as possible. We host all resources locally (no third-party CDNs) so that you only have to connect to one domain. The website should be easy to browse using Tor Browser and with scripts blocked. We also have an `onion service <http://qubesosfasa4zl44o4tws22di6kepyzfeqv3tg4e3ztknltfxqrymdad.onion/>`__ (access is not logged). We even go out of our way to make it easy to download `this website’s git repo <https://github.com/QubesOS/qubesos.github.io>`__, including all the website source code, so that you can host this entire site from your own local machine offline.
+
+Most of the website is written in Markdown so that the plain text can be enjoyed from the comfort of your terminal.
+Obviously, we don’t use any ads or trackers, but this is still a public website, so man-in-the-middle attacks and such are always a possibility. Please be careful. See :ref:`FAQ: Should I trust this website? <introduction/faq:should i trust this website?>`
+
+Qubes OS documentation
+----------------------
+
+Qubes OS documentation is hosted on `Read The Docs <https://readsthedocs.com/>`__.
+We’ve converted all of the :doc:`documentation </index>` from Markdown to reStructuredText. You can enjoy the plain text from the comfort of your terminal. Here’s the `repo <https://github.com/QubesOS/qubes-doc>`__. (By the way, Git tags on our repos are PGP-signed so you can :doc:`verify </project-security/verifying-signatures>` the authenticity of the content.) We omit the ethical ads from RTD, but this is still a public website, so man-in-the-middle attacks and such are always a possibility. Please be careful. 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?>`.
+
+Please refer to RTD's `privacy policy <https://docs.readthedocs.com/platform/stable/privacy-policy.html>`__
+for more information.
+As per RTD site, the TL;DR version is as follows:
+
+.. code:: text
+
+   RTD collects information only with consent; only the minimum amount of personal information that is necessary to fulfill the purpose of the interaction with RTD;
+   doesn’t sell it to third parties; and only use it as the above Privacy Policy describes.
+
 
 Update Servers and Repositories
 -------------------------------