Add a quick reference for rst markup.

[ezio-melotti]

This PR adds a quick reference table at the top of the rst reference page. The goal of this table is to show some commonly used markup and to include links to the relevant sections. I also added some internal references and changed a title.

This was proposed a decade ago on IRC, and then captured in python/cpython#58426 (comment) ¹

Footnotes

1. note that the issue itself (now transferred to include rendered output in addition to markup #14) is probably obsolete, and this proposal doesn't aim to solve that. ↩

[CAM-Gerlach]

IMO, this PR is definitely a great improvement from a reader quick-reference perspective.

I do think, like for PEP 12, we shouldn't duplicate the Sphinx reST primer nearly word for word in most places, as opposed to just linking to it (via Intersphinx) and focusing on the guidance and conventions unique and specific to the CPython docs. I've opened python/docs-community#57 to discuss that issue further.

[ezio-melotti]

Here is a new iteration:

• added parameters next to arguments
• merged vars/literals/code
• added examples of roles with custom text, without links, without the first part¹.

I didn't add methods/classes as discussed in a previous comment. The goal of this table is to provide a quick reminder for the syntax (e.g. how do I create a link? or a coment? was it .. directive: or .. directive::?) -- additional roles (like meth or class) are just a click away.

Footnotes

1. the descriptions in the first column are not too accurate, but IMHO functional enough. People that already know that e.g. there's a way to only show the last component of an object will recognize the entry and see the syntax in the table; people that are not familiar with the feature or find the description confusing can always click the link and find a more exhaustive description. ↩

[CAM-Gerlach]

Looks good overall with your changes 👍 , I just had some textual improvements, minor nits and bikeshedding

[ezio-melotti]

I believe I addressed all comments. This is the latest iteration of the table:

I also had to use a couple of rst tricks for .. and ``...``, but I was able to get it to work using :literal:`...`:

[CAM-Gerlach]

I suggested some re-writes to the roles section to avoid parts that are contradictory, duplicative and potentially confusing. Otherwise, this looks pretty good overall.

[CAM-Gerlach]

Two tiny tweaks, otherwise LGTM 👍

[ezio-melotti]

Merged. thanks for the review and suggestions!