search

aio-libs / aiobotocore

asyncio support for botocore library using aiohttp
https://aiobotocore.aio-libs.org
Apache License 2.0
1.16k stars 182 forks source link

Improve use of Sphinx syntax #1162

Closed jakob-keller closed 2 weeks ago

jakob-keller commented 3 weeks ago 
          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 https://github.com/aio-libs/aiobotocore/pull/1160#discussion_r1724142565_

jakob-keller commented 3 weeks ago

Also: https://github.com/aio-libs/aiobotocore/pull/1160#discussion_r1724142856

webknjaz commented 3 weeks ago

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 commented 2 weeks ago

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

webknjaz commented 2 weeks ago

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...