mirror of
https://github.com/QubesOS/qubes-doc.git
synced 2025-12-14 23:45:07 -05:00
80c9edac96
- Cleared misunderstandings of disposable templates, this word was
sometimes used interchangeably with disposables;
- Deduplicate content as much as possible;
- Reference other pages or previous sections;
- Assume the user has read the previous sections up until the
current section they are reading;
- All this deduplication enables easier reading, less clutter, but
each section doesn't stand by itself, each page does. Some things
were reinforced on multiple sections, but limited to when
extremely necessary to learn by reinforcement;
- Structure the files to their distinct use cases:
- how-to-use-disposables is just the basics to learn what are
disposables and how to use them, using GUI and CLI alternatives;
- disposable-customization has everything advanced related to
disposables, such as advanced usage, creation of disposables
templates, their customization;
- disposable-implementation assumes the user understand the previous
pages and contains a more technical description of disposables and
preloaded disposables as well as their implementation;
- Prepared usage for a GUIVM setup, avoiding mentions to dom0;
- Usage modes has been organized in GUI first and CLI second, grouped by
origin such as GUIVM and app qube;
- Usage page restricts itself to "default-dvm", it's name is not
variable like the Whonix disposable template variant and it is the
most used disposable template, thus we avoid variables replacement
that the user should think of the value to a definitive value to use
when learning. Customization page could not benefit much from this
though, as it is intended to create alternative disposable templates;
- Usage page links to Tails documentation of why using it on a VM is not
amensiac, so it can be referenced for users that ask to have Tails in
a VM for anti-forensics purposes;
- Updated the images to R4.3, nobody deserves to see the Qubes version
of the Xfce application menu anymore when the new app menu rocks. The
images also had to be updated because it was fullscreen screenshot
on a large resolution, making it very difficult to read unless
opening the image in a new tab and zooming in;
- Implementation page shows preloaded disposables alternatives that were
once used or considered as a comparative for future studies, to answer
why a different option is not being used and what requirements a
replacement must meet;
- Content from previous releases have been deleted;
- Updates to Qrexec policy v4;
- Use rST roles;
- Change non-ASCII quotes and em-dashes to ASCII;
- Standardized text writing style, many people have contributed to these
pages over the years, there is a lot of different writings styles
which make the text difficult to map. I rewrote a lot of the
paragraphs to my liking and understanding of the different stages that
a user may go through when using disposables, and even on paragraphs
that I didn't completely write, it was modified to follow the same
standard with the rest of the pages. The usage must be very simple
with just the basics, we don't want to scare the user's off of using
disposables, we want to convince them. The customization is a bit more
advanced, it assumes a lot more knowledge from the user to make
decisions by themselves such as customizing applications and qube
settings, which can affect system security. The implementation details
do not require reading the code, it just exist to explain what is
being used and why it was chosen.
Fixes: https://github.com/QubesOS/qubes-issues/issues/10282
For: https://github.com/QubesOS/qubes-issues/issues/1512
162 lines
4.9 KiB
Python
162 lines
4.9 KiB
Python
"""qubes-doc configuration file"""
|
|
|
|
import os
|
|
import sys
|
|
from pathlib import Path
|
|
|
|
# Append the path to custom extensions
|
|
sys.path.append(str(Path('_ext').resolve()))
|
|
|
|
# For the full list of options, see the documentation:
|
|
# https://www.sphinx-doc.org/en/master/usage/configuration.html
|
|
|
|
|
|
# -- Project information -----------------------------------------------------
|
|
|
|
project = 'Qubes OS'
|
|
author = 'Qubes OS Project'
|
|
copyright = f'%Y, {author}'
|
|
|
|
# Warning: Sphinx's version and release differ from Qubes OS !
|
|
|
|
# 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.2.4'
|
|
|
|
|
|
# -- General configuration ---------------------------------------------------
|
|
|
|
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
|
|
'youtube_frame', # Embed YouTube videos
|
|
]
|
|
|
|
# Redirects for specific URLs as fall back
|
|
redirects = {
|
|
"user/hardware/hcl":
|
|
"https://www.qubes-os.org/hcl/",
|
|
"user/downloading-installing-upgrading/downloads:mirrors":
|
|
"https://www.qubes-os.org/downloads/mirrors/",
|
|
"developer/general/visual-style-guide":
|
|
"https://www.qubes-os.org/doc/visual-style-guide/",
|
|
"user/downloading-installing-upgrading/downloads":
|
|
"https://www.qubes-os.org/downloads/",
|
|
|
|
# user/templates/windows URLs
|
|
"user/templates/windows/windows-qubes-4-1":
|
|
"qubes-windows.html",
|
|
"user/templates/windows/windows-qubes-4-0":
|
|
"qubes-windows.html",
|
|
"user/templates/windows/qubes-windows-tools-4-1":
|
|
"qubes-windows-tools.html",
|
|
"user/templates/windows/qubes-windows-tools-4-0":
|
|
"qubes-windows-tools.html",
|
|
"user/templates/windows/migrate-to-4-1":
|
|
"qubes-windows-migrate.html",
|
|
}
|
|
|
|
# -- -- Options for highlighting ---------------------------------------------
|
|
|
|
# Disable syntax highlighting
|
|
highlight_language = 'none'
|
|
|
|
# Set the Pygments style for syntax highlighting
|
|
pygments_style = 'sphinx'
|
|
|
|
# -- -- Options for source files ---------------------------------------------
|
|
|
|
# Patterns to exclude from the source directory
|
|
exclude_patterns = [
|
|
'_*',
|
|
'**/.*',
|
|
'**/*.txt',
|
|
'attachment',
|
|
'.venv',
|
|
]
|
|
|
|
|
|
# -- Builder options ---------------------------------------------------------
|
|
|
|
# -- -- Options for HTML output ----------------------------------------------
|
|
|
|
html_theme = 'sphinx_rtd_theme'
|
|
|
|
html_title = f'{project} Documentation'
|
|
|
|
html_theme_options = {
|
|
'style_external_links': True,
|
|
'collapse_navigation': True,
|
|
}
|
|
|
|
html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "/")
|
|
|
|
html_static_path = ['attachment/doc']
|
|
|
|
html_use_opensearch = "https://doc.qubes-os.org"
|
|
|
|
html_logo = "attachment/icons/128x128/apps/qubes-logo-icon.png"
|
|
html_favicon = "attachment/icons/favicon-16x16.png"
|
|
|
|
# -- -- Options for the linkcheck builder ------------------------------------
|
|
|
|
linkcheck_anchors = False
|
|
linkcheck_ignore = [r'^https?://[^/\s]+\.onion']
|
|
|
|
# -- Extensions configuration ------------------------------------------------
|
|
# Prefix section labels with the document name
|
|
autosectionlabel_prefix_document = True
|
|
|
|
# Allows references to the docs in dev.qubes-os.org
|
|
# i.e.: :doc:`core-admin:libvirt`
|
|
intersphinx_mapping = {
|
|
'core-admin': ('https://dev.qubes-os.org/projects/core-admin/en/latest/', None),
|
|
'core-admin-client': ('https://dev.qubes-os.org/projects/core-admin-client/en/latest/', None),
|
|
'core-qrexec': ('https://dev.qubes-os.org/projects/qubes-core-qrexec/en/stable/', None),
|
|
}
|
|
intersphinx_disabled_reftypes = ["*"]
|
|
|
|
# Open Graph image for social media sharing
|
|
ogp_image = "https://www.qubes-os.org/attachment/icons/qubes-logo-icon-name-slogan-fb.png"
|
|
# Disable Open Graph image alt text
|
|
ogp_image_alt = False
|
|
|
|
# -- HTML configuration ------------------------------------------------------
|
|
|
|
|
|
# -- -- Add 'Edit on GitHub' Link --------------------------------------------
|
|
|
|
html_context = {
|
|
"display_github": True,
|
|
"github_user": "QubesOs",
|
|
"github_repo": "qubes-doc",
|
|
"github_version": "rst",
|
|
"conf_py_path": "/",
|
|
}
|
|
|
|
# -- -- Options for internationalisation -------------------------------------
|
|
|
|
# Directories containing translation files
|
|
locale_dirs = ['_translated']
|
|
|
|
gettext_compact = False
|
|
|
|
gettext_uuid = True
|
|
|
|
# -- -- Options for markup ---------------------------------------------------
|
|
|
|
# Define a block of reusable reStructuredText (reST) snippets, warnings etc. that Sphinx automatically appends to every source file before it is parsed
|
|
rst_epilog = """
|
|
.. |debian-codename| replace:: bookworm
|
|
.. |debian-version| replace:: 12
|
|
.. |qubes-logo-icon| image:: /attachment/icons/128x128/apps/qubes-logo-icon.png
|
|
:height: 1em
|
|
:class: no-scaled-link
|
|
:alt: Qubes logo icon
|
|
"""
|