Merge cf74e567fb into ba609d123e

.gitignore

@@ -0,0 +1 @@
+_build

.readthedocs.yaml

@@ -10,7 +10,7 @@ submodules:
   recursive: true
 
 sphinx:
-  builder: html
+  builder: dirhtml
   configuration: conf.py
   fail_on_warning: false
 

_ext/videos.py

@@ -0,0 +1,68 @@
+"""
+    ReST directive for embedding Youtube and Vimeo videos.
+
+    There are two directives added: ``youtube`` and ``vimeo``. The only
+    argument is the video id of the video to include.
+    Both directives have three optional arguments: ``height``, ``width``
+    and ``align``. Default height is 281 and default width is 500.
+
+    Example::
+
+        .. youtube:: anwy2MPT5RE
+           :height: 315
+           :width: 560
+           :align: left
+
+    :copyright: (c) 2012 by Danilo Bargen.
+    :license: BSD 3-clause
+
+    From https://gist.github.com/ehles/bed012d78aad5d3cd6c35a49bef32f9f
+"""
+from __future__ import absolute_import
+from docutils import nodes
+from docutils.parsers.rst import Directive, directives
+
+def align(argument):
+    """Conversion function for the "align" option."""
+    return directives.choice(argument, ('left', 'center', 'right'))
+
+
+class IframeVideo(Directive):
+    has_content = False
+    required_arguments = 1
+    optional_arguments = 0
+    final_argument_whitespace = False
+    option_spec = {
+        'height': directives.nonnegative_int,
+        'width': directives.nonnegative_int,
+        'align': align,
+    }
+    default_width = 500
+    default_height = 281
+
+    def run(self):
+        self.options['video_id'] = directives.uri(self.arguments[0])
+        if not self.options.get('width'):
+            self.options['width'] = self.default_width
+        if not self.options.get('height'):
+            self.options['height'] = self.default_height
+        if not self.options.get('align'):
+            self.options['align'] = 'left'
+        return [nodes.raw('', self.html % self.options, format='html')]
+
+
+class GeneralVid(IframeVideo):
+    html = '<iframe src="%(video_id)s" width="%(width)u" height="%(height)u" frameborder="0" webkitAllowFullScreen mozallowfullscreen allowfullscreen class="responsive" referrerpolicy="no-referrer" scrolling="no"></iframe>'
+
+
+class Youtube(IframeVideo):
+    html = '<iframe src="https://www.youtube-nocookie.com/embed/%(video_id)s" \
+    width="%(width)u" height="%(height)u" frameborder="0" \
+    webkitAllowFullScreen mozallowfullscreen allowfullscreen \
+    class="responsive" referrerpolicy="no-referrer" scrolling="no"></iframe>'
+
+
+def setup(builder):
+    directives.register_directive('youtube', Youtube)
+    directives.register_directive('generalvid', GeneralVid)
+

conf.py

@@ -1,133 +1,108 @@
-"""
+"""qubes-doc configuration file"""
-  ReST directive for embedding Youtube and Vimeo videos.
+
-  There are two directives added: ``youtube`` and ``vimeo``. The only
+import os
-  argument is the video id of the video to include.
+import sys
-  Both directives have three optional arguments: ``height``, ``width``
+from pathlib import Path
-  and ``align``. Default height is 281 and default width is 500.
+
-  Example::
+sys.path.append(str(Path('_ext').resolve()))
-    .. youtube:: anwy2MPT5RE
+
-      :height: 315
+# For the full list of options, see the documentation:
-      :width: 560
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
-      :align: left
+
-  :copyright: (c) 2012 by Danilo Bargen.
-  :license: BSD 3-clause
-"""
-from __future__ import absolute_import
-from docutils import nodes
-from docutils.parsers.rst import Directive, directives
 
 # -- Project information -----------------------------------------------------
 
 project = 'Qubes OS'
-copyright = '2025, Qubes OS Project'
 author = 'Qubes OS Project'
+copyright = f'%Y, {author}'
 
-title = "Qubes Docs"
+# Warning: Sphinx's version and release differ from Qubes OS !
-html_title = "Qubes Docs"
+
+# The major project version, used as the replacement for the |version| default
+# substitution. i.e. '4.3'
+version = '4.2'
 
 # The full version, including alpha/beta/rc tags
-release = '4.3'
+release = '4.2.4'
+
 
 # -- General configuration ---------------------------------------------------
 
-html_static_path = ['attachment/doc']
 extensions = [
   'sphinx.ext.autosectionlabel',
   'sphinxnotes.strike',
-  'sphinx_reredirects'
+  'sphinx_reredirects',
+  'videos',
 ]
 
 redirects = {
-  "user/hardware/hcl": "https://www.qubes-os.org/hcl/",
+    "user/hardware/hcl":
-  "user/downloading-installing-upgrading/downloads:mirrors":"https://www.qubes-os.org/downloads/mirrors/",
+        "https://www.qubes-os.org/hcl/",
-  "developer/general/visual-style-guide": "https://www.qubes-os.org/doc/visual-style-guide/",
+    "user/downloading-installing-upgrading/downloads:mirrors":
-  "developer/general/website-style-guide":"https://www.qubes-os.org/doc/website-style-guide/",
+        "https://www.qubes-os.org/downloads/mirrors/",
-  "user/downloading-installing-upgrading/downloads":"https://www.qubes-os.org/downloads/",
+    "developer/general/visual-style-guide":
-  "developer/general/how-to-edit-the-documentation":"https://www.qubes-os.org/doc/how-to-edit-the-documentation/"
+        "https://www.qubes-os.org/doc/visual-style-guide/",
+    "developer/general/website-style-guide":
+        "https://www.qubes-os.org/doc/website-style-guide/",
+    "user/downloading-installing-upgrading/downloads":
+        "https://www.qubes-os.org/downloads/",
+    "developer/general/how-to-edit-the-documentation":
+        "https://www.qubes-os.org/doc/how-to-edit-the-documentation/",
 }
 
-autosectionlabel_prefix_document = True
 
-source_suffix = {
+# -- -- Options for highlighting ---------------------------------------------
-  '.rst': 'restructuredtext',
+
-}
+highlight_language = 'none'
-templates_path = ['_templates']
+
+
+# -- -- Options for source files ---------------------------------------------
 
-root_doc = "index"
 exclude_patterns = [
-  '_dev/*',
+  '_*',
-  'attachment/*',
+  '**/.*',
   '**/*.txt'
+  'attachment',
 ]
 
+
+# -- Builder options ---------------------------------------------------------
+
+# -- -- Options for HTML output ----------------------------------------------
+
 html_theme = 'sphinx_rtd_theme'
-# html_theme = 'default'
+
-# html_theme = 'classic'
+html_title = f'{project} {release} Documentation'
 
 html_theme_options = {
-  'externalrefs': True,
+  'style_external_links': True,
-  'bgcolor': 'white',
-  'linkcolor': '#99bfff',
-  'textcolor': '#000000',
-  'visitedlinkcolor': '#7b7b7b',
-  'bodyfont': '"Open Sans", Arial, sans-serif',
-  'codebgcolor': '$color-qube-light',
-  'codebgcolor': 'grey',
   'body_min_width': '50%',
   'body_max_width': '90%',
   'collapse_navigation': True,
 }
 
-gettext_uuid = True
+html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "/")
-gettext_compact = False
 
-# epub_show_urls = 'footnote'
+html_static_path = ['attachment/doc']
-# latex_show_urls ='footnote'
 
+html_use_opensearch = "https://doc.qubes-os.org"
+
+# -- -- Options for the linkcheck builder ------------------------------------
+
+linkcheck_anchors = False
+linkcheck_ignore = [r'^https?://[^/\s]+\.onion']
+
+# -- Extensions configuration ------------------------------------------------
+
+autosectionlabel_prefix_document = True
+
+
+# -- HTML configuration ------------------------------------------------------
+
+# -- -- Options for internationalisation -------------------------------------
 
 locale_dirs = ['_translated']
 
-# from https://gist.github.com/ehles/bed012d78aad5d3cd6c35a49bef32f9f
+gettext_compact = False
-def align(argument):
-  """Conversion function for the "align" option."""
-  return directives.choice(argument, ('left', 'center', 'right'))
 
-
+gettext_uuid = True
-class IframeVideo(Directive):
-  has_content = False
-  required_arguments = 1
-  optional_arguments = 0
-  final_argument_whitespace = False
-  option_spec = {
-    'height': directives.nonnegative_int,
-    'width': directives.nonnegative_int,
-    'align': align,
-  }
-  default_width = 500
-  default_height = 281
-
-  def run(self):
-    self.options['video_id'] = directives.uri(self.arguments[0])
-    if not self.options.get('width'):
-      self.options['width'] = self.default_width
-    if not self.options.get('height'):
-      self.options['height'] = self.default_height
-    if not self.options.get('align'):
-      self.options['align'] = 'left'
-    return [nodes.raw('', self.html % self.options, format='html')]
-
-
-class GeneralVid(IframeVideo):
-  html = '<iframe src="%(video_id)s" width="%(width)u" height="%(height)u" frameborder="0" webkitAllowFullScreen mozallowfullscreen allowfullscreen class="responsive" referrerpolicy="no-referrer" scrolling="no"></iframe>'
-
-
-class Youtube(IframeVideo):
-  html = '<iframe src="https://www.youtube-nocookie.com/embed/%(video_id)s" \
-  width="%(width)u" height="%(height)u" frameborder="0" \
-  webkitAllowFullScreen mozallowfullscreen allowfullscreen \
-  class="responsive" referrerpolicy="no-referrer" scrolling="no"></iframe>'
-
-
-def setup(builder):
-  directives.register_directive('youtube', Youtube)
-  directives.register_directive('generalvid', GeneralVid)