Notes about Qubes OS documentation(s)

Biggest issue: image accessibility

Todo

Finalize the following + mail to qubes-devel

The way Sphinx and Docutils treat images and links has many flaws. When an image is inside a link without any text, the alternative text should describe the link function, not the image. So even with non-empty alt, that’s not a good situation. It is of course worst with empty alts.

from sphinx.application import Sphinx
from sphinx.builders.html import StandaloneHTMLBuilder
from sphinx.util.typing import ExtensionMetadata

from docutils import nodes

import posixpath


class FixStandaloneHTMLBuilder(StandaloneHTMLBuilder):
    name = "html"
    html_scaled_image_link = False

    def post_process_images(self, doctree: Node) -> None:
        super().post_process_images(doctree)

        for node in doctree.findall(nodes.image):
            if not any((key in node) for key in ("scale", "width", "height")):
                # resizing options are not given. scaled image link is available
                # only for resized images.
                continue
            if isinstance(node.parent, nodes.reference):
                # A image having hyperlink target
                continue
            if "no-scaled-link" in node["classes"]:
                # scaled image link is disabled for this node
                continue

            uri = node["uri"]

            parent = nodes.paragraph("")
            reference = nodes.reference("", f"Link to {node['uri']}", internal=True)
            parent.append(reference)

            if uri in self.images:
                reference["refuri"] = posixpath.join(self.imgpath, self.images[uri])
            else:
                reference["refuri"] = uri

            node.parent.append(parent)


def setup(app: Sphinx) -> ExtensionMetadata:
    app.add_builder(FixStandaloneHTMLBuilder, override=True)

    return {
        "version": "0.1",
        "env_version": 1,
        "parallel_read_safe": True,
        "parallel_write_safe": True,
    }

Tips to contribute

• do not use code (see related issue in sphinx-doc/sphinx repo)

• you can separate your workflow using:

  • Split GPG-2

  • sys-ssh-agent

  • a qube where you trigger your builds using git-patch

Issues

Currently working on

• Add the community doc “How to open URLs/files in other VMs” to the official docs (still a lot to do!)

• Be clear about the exact release targeted by the documentation and its status (needs review)

• Improve the “Command-Line Tools” reference web page (needs review, there is more to do but not now)

• Remove ads from documentation (I need an answer from Marek)

• Collect all existing documentation and publish it, see also:

  • Create a sphinx doc for qubes-builderv2 and put it on RTD

  • Create a sphinx doc for qubes-app-linux-img-converter and put it on RTD

  • Create a sphinx doc for qvm-create-windows-qube and put it on RTD

  • Create proper sphinx docs for qubes-mgmt-salt and put it on RTD

  • Create proper sphinx docs for qubes-core-admin-linux and put it on RTD

  • Create proper sphinx docs for qubes-desktop-linux-common and put it on RTD

  • Add qubes-video-companion to Read the docs

Things to do

• Remove unused code related to :ticket: role in qubes-core-admin dochelpers

Issues about the structure / maintainance

• Provide a hierarchy in the How-to guides of the documentation

• Better integration between “How to use devices” pages and “qvm-device” documentation

• Add a way to review documentation pages

• Remove duplicated dependencies in qubes-doc

Build issues

• Offline documentation

• Orchestrate documentation build with disposable qube

Good ideas

• User-focused documentation of qubesctl/saltstack

• Improve supportive images of GUI in documentation

  Todo

  proposal to use a SVG template with a grammar of shapes, texts, etc. using the original screenshot embed and CSS styles for consistency. Maybe override the SVG attributes to allow only a limited set and keep things consistent? SVG is editable in all sorts of editors, from a text editor to a browser, including Inkscape.

Missing parts

• Document device “self-identity oriented” assignment in user documentation

Waiting for a review

• Visual Style Guide page was not migrated to RST and is not present in RTD

Other things

• Confusing mention of “hard wrap” in the documentation style guide

• Clarify the “Verifying signature” documentation page to help users following it

• Provide a decision tree for reStructuredText markup in docs

• Remove useless references to minimal templates and make it clear why we should not promote their use! I.e.: How to organize your qubes Rewrite Minimal templates introduction, add a second admonition, like attention to break the style and make sure the user feel incomfortable with this page?

No one seems to care

• Read the docs search box is very laggy

Ideas that needs to be tested/discussed or raised as issues/PR

Missing references everywhere

In their current state, the docs are poorly cross-referenced. And when you try to change this, it’s a rabbit hole. A potential plan to study would be:

1. create inline internal targets to reference something with having to do much more work

2. make any the default role. There will be issues, as the default role has been used as a way to display literal code. Probably other issues too.

3. we can introduce a new “QubesOS” domain with custom directives and roles: :policy:, :service:, :event: (already in Welcome to core-admin’s documentation!)

Quick references that I generally need but doesn’t exist:

• programs (qvm-...)

• RPC services (qubes.ConvertPdf)

• prefs

• features

• services from qvm-service

• RPC policy syntax (@default, etc.)

An index could be useful?

See if something is possible with Index

Unified markup

We need to unify the restructuredtext markups accross all repos. I encountered this issue will trying to help @ben-grande on the rewriting of the documentation about disposables. Some ideas:

• use the same intersphinx_mapping everywhere (issue raised by @marmarek: the number of http requests send to unused repos)

• do not limit the doc (issues ?)

Unified build process

It is possible to use submodules in qubes-doc to build all the docs at once in one repo. We can also share a common conf.py base.

A way to test the docs?

Sphinx can test the code snippets but how about having a way to test a how-to?

Create openqa tests related to a how-to? That would be very difficult to maintain?

Keep screenshots updated

This is the documentation of an OS, as such, we might need far more tools than the regular docs.

Ideas:

• automatic way to retrieve pictures from qubes-artwork or from openqa

• SVG template for editing a screenshot in a way that allows maintainers to update the screenshot while keeping the shapes on top of it?

Warning

This need to be user friendly. HOW?!

General direction

Am I really able to do something useful? Maybe start by having a proper reference and them, build tutorials???