Update documentation guidelines about references

[parulin]

At first, this PR was meant to fix QubesOS/qubes-issues#10321 but I ended up doing some other things, related to the RST style guide / How to edit the docs:

• correct some URLs for linkcheck
• "TL;DR: Cross-referencing" is now a real "TL;DR:" about the most common use cases. Anything else resides in the style guide
• The cross-referencing explicit label now is attached to the Cross-referencing section of the style guide
• Examples of the rst syntax have been simplified as much as possible
• do not insist on the glossary directive
• add :program: role
• detail each way of using cross-references in paragraphs separated by headers
• try to clarify the use of hyperlinks (confusing absolute/relative URLs from the website?)
• limit the presentation of the header levels to the bare minimum
• developed and consistent Markdown Cheatsheet

[parulin]

I think it could be a good idea to split the RST style guide with:

1. a tutorial about the use of RST in qubes-doc
2. a style guide, focusing on guideline narrowing the use of the syntax (i.e.: header levels, embedded links, etc.

Two other TL;DR of the How to edit the docs could be simplified too.

[unman]

What is the advantage of this change? Does it not make it more difficult for contributors? I think it cannot be used for links within pages, so we end up with two forms for links in the docs.

[unman]

The VPN guide should be in the official docs, with a link there to the meta list.
I think the Salt and Ansible guides should also be in official docs.
I have tested few of the others. Some of them are guides fraught with potential issue for users - minifying templates, changing firewall, etc. Some (like 3wm, mutt) are special interest.

I think that links to external sites should carry a health warning to say that they are not endorsed.
The only way I can see of doing this is to have a separate index page with this information and take individual links from the main index.

[unman]

and THAT was in the wrong issue

[parulin]

What is the advantage of this change? Does it not make it more difficult for contributors? I think it cannot be used for links within pages, so we end up with two forms for links in the docs.

Are you talking about the roles using :py:class:...? We already have two forms for links in the docs: :doc: and :ref:. The roles relative to code objects are for developers.

Everything I tried to describe is already used in the documentation. It was already difficult to use (see the discussion about #1554) so I'm trying to clarify how to use Sphinx in the Qubes documentation context.