Documentation: Modernization and copy-editing

[amotl]

Some copy editing across the board, with a focus on wording, linking, and formatting.

[hammerhead]

Very nice to have those direct links! Do you know why one renders in bold and the other one doesn't?

[amotl]

That's weird, thanks for spotting. I do not have an idea yet, why this is happening.

[amotl]

Observations I

<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#list" title="(in Python v3.11)">
  <code class="docutils literal notranslate">
    <span class="pre">list</span>
  </code>
</a>

<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#dict" title="(in Python v3.11)">
  <code class="xref py py-class docutils literal notranslate">
    <span class="pre">dictionaries</span>
  </code>
</a>

It looks like the xref class (from basic.css) adds the font-weight: bold; CSS directive.

Observations II

Funny enough, when rendering locally (not on RTD), those additional code tags, including the corresponding classes, are not rendered at all. Instead, the HTML looks like this:

<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#lists">list</a>
<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#dict">dictionaries</a>

And visually, it looks like this, which I think would be good.

Next steps

So, I guess we will need to find out why the HTML output is different when being built on/by RTD.

[amotl]

After resetting my local sandbox environment, I am also getting the same results as above, where the rendered HTML at this spot includes <code> tags, and where the same CSS classes xref py py-class are present on the :class:dictionaries <py:dict> link.

It looks like the custom label, dictionaries, is responsible for the additonal xref py py-class classes, and xref makes the link label render in bold.

[amotl]

I have not been able to discover the root cause, so I fixed it with crate/crate-docs-theme#366.

[amotl]

With the patch to crate-docs-theme, it now looks like this: