Improve use of Sphinx syntax

[jakob-keller]

          FWIW, there's a dedicated Sphinx role for files:

1. Download sources of the release of botocore you're trying to upgrade to, and the version of botocore that aiobotocore is currently locked to (see :file:`pyproject.toml`) and do a folder based file comparison of the botocore folders (tools like DiffMerge are nice).

Originally posted by @webknjaz in #1160 (comment)

[jakob-keller]

Also: #1160 (comment)

[webknjaz]

When calling Sphinx, pass -n -W --keep-going and set default_role = 'any' in conf.py. This will reveal the problems that need to be addressed.

[jakob-keller]

There is also #879. Should conversion to markdown be prioritised over improving RST?

[webknjaz]

Partially, maybe. You can still enforce strictness in Sphinx. And then, you need to fix the references regardless of which syntax is used.

Additionally, to support inclusion of Markdown files into the Sphinx docs, you'll need to plug MyST-parser there and convert the index document into Markdown (maybe a few more docs, too). I think I have an example of that in pip-tools.

So I'd probably make the conversion depend on everything else...