Documentation on the onion server

[unman]

There are some issues with web site and documentation on the onion server.

Many of the pages now contain redirects hard coded redirects to doc.qubes-os.org.
RTD offers the possibility of versioned documentation.

I do not think it will be possible to have a local instance of RTD on
the server.

I propose to:
1. Generate documentation for latest and stable (whatever names are
used) on the server.
2. Rewrite the redirects to a doc instance on the onion server, using
whatever the default view is in RTD.
3. If headers are included which reference another version, then rewrite
THOSE links to point to the relevant onion site.
4. Generate PDF and EPUB versions and reference them from the
documentation.

There is an open issue for extending the explanation of mirrors and the
onion sites on the download pages.
I would like to rewrite the download links to point to the onion server,
with pointers to the clear site download.

The aim should be to minimise the possibility of users on the onion
inadvertently clicking through to the clear.

There has been a suggestion that we could run a proxy on the onion
redirecting to the clearnet sites. I do not think this is a workable
solution because it raises significant risks to anonymity.

Thoughts or input?

[Marek Marczykowski-Górecki]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

On Fri, Oct 10, 2025 at 01:52:23PM +0100, 'unman' via qubes-devel wrote:
> There are some issues with web site and documentation on the onion server.
>
> Many of the pages now contain redirects hard coded redirects to doc.qubes-os.org.

This can be avoided, I think? I see some instances of "doc.qubes-os.org"
in the qubes-doc repo, but there are like 8 of them and it should be
possible to replace them with relative links I hope. During migration
testing, we did several local builds, and accessing it via localhost
worked fine, didn't redirect to doc.qubes-os.org.

> RTD offers the possibility of versioned documentation.

The switcher seems to be part of the rtd theme:
https://github.com/readthedocs/sphinx_rtd_theme
https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html#confval-version_selector
But it says it depends on RTD addon. I think it's somewhere here:
https://github.com/clemfromspace/rtd-with-docsearch
but it looks complicated to setup standalone version of that.

> I do not think it will be possible to have a local instance of RTD on
> the server.
>
> I propose to:
> 1. Generate documentation for latest and stable (whatever names are
> used) on the server.
> 2. Rewrite the redirects to a doc instance on the onion server, using
> whatever the default view is in RTD.
> 3. If headers are included which reference another version, then rewrite
> THOSE links to point to the relevant onion site.
> 4. Generate PDF and EPUB versions and reference them from the
> documentation.

Looks like a good idea.

> There is an open issue for extending the explanation of mirrors and the
> onion sites on the download pages.
> I would like to rewrite the download links to point to the onion server,
> with pointers to the clear site download.
>
> The aim should be to minimise the possibility of users on the onion
> inadvertently clicking through to the clear.

As a safety measure, there can be sanity check that searches for
https://doc.qubes-os.org in built side. But in practice, the risk to the
user is not that big - since they access the onion site, they connect
via Tor. This means if it goes to doc.qubes-os.org, it will still go
through Tor. Depending on exit node, might be slower, but should not
leak the user IP.

> There has been a suggestion that we could run a proxy on the onion
> redirecting to the clearnet sites. I do not think this is a workable
> solution because it raises significant risks to anonymity.
>
> Thoughts or input?

- --
Best Regards,
Marek Marczykowski-Górecki
Invisible Things Lab
-----BEGIN PGP SIGNATURE-----

iQEzBAEBCAAdFiEEhrpukzGPukRmQqkK24/THMrX1ywFAmjpC+YACgkQ24/THMrX
1yxm+gf8DibzjTERWGjJILiSiOIqnNm7it5X+xNwR/wSbj6d8xXd1IofpIAGFHcH
SSgypnWfaq3f6gfwGz6P0/WQK0e95/irG6wwmhO9VyY8lGRbTiIsa7Qp97zaNdrb
2gami3xEdfhi6Wqq/Ba8t/5V4xBzUL7AKjSbq/35+tD/DI+yGczMVisrW25hPhyK
Rn0E20qpsEtUWE0KNmf5nfXX1lsA8UDKnreQx+DFc0mUnK+xwCuD4Z5BcAO8tWKQ
mYTs/NLX5sQwfAjU2VmW+Hjny7QSvNoMxYRpxSsOLyr4NgtUEN3OXKoSYJeRTZC5
OlZ7qVp7kt2ya340Zc0KoIVbtaFB0w==
=JWNv
-----END PGP SIGNATURE-----