chore(docs): ⬆️ upgrade Sphinx and related dependencies to latest versions

[Paillat-dev]

Summary

The dependencies need to be upgraded together in order to be able to upgrade to sphinx v9.
This is currently a work in progess, specifically because of python-trio/sphinxcontrib-trio#399 which prevents this pr from building docs currently. Since the aforementioned project seems abandoned, we will most likely need to find a solution ourselves.

Information

• This PR fixes an issue.
• This PR adds something new (e.g. new method or parameters).
• This PR is a breaking change (e.g. methods or parameters removed/renamed).
• This PR is not a code change (e.g. documentation, README, typehinting,
  examples, ...).

Checklist

• I have searched the open pull requests for duplicates.
• If code changes were made then they have been tested.
  • I have updated the documentation to reflect the changes.
• If type: ignore comments were used, a comment is also left explaining why.
• I have updated the changelog to include these changes.

[pycord-app]

Thanks for opening this pull request!
Please make sure you have read the Contributing Guidelines and Code of Conduct.

This pull request can be checked-out with:

git fetch origin pull/3067/head:pr-3067
git checkout pr-3067

This pull request can be installed with:

pip install git+https://github.com/Pycord-Development/pycord@refs/pull/3067/head

[Paillat-dev]

After doing some research, the main issue arising is the lack of support for documenting context managers and generators (:async-for:, :async-with:). The rest, notably :decorator: for our specific purpose, can be replaced with .. autodecorator. I still need to research :async: usage, which was introduced in sphinx 2.1.0, but sphinxcontrib-trio provided autodetection for. I hope sphinx can natively detect wether a function is a coroutinefunction, it should make our work easier.

Ref: sphinx-doc/sphinx#3743

[Paillat-dev]

After some testing, below is the difference between an async method with sphinxcontrib-trio and without. Both are autodetected, but they show await and async as prefix, respectively.

sphinx with sphinxcontrib-trio

bare sphinx

[Paillat-dev]

Update, it seems like .. autodecorator creates a "function" from sphinx's point of view, which means it is excluded from our custom .. attributetable. We would need to either implement our own :decorator: or something similar, or modify .. autodecorator to not ignore functions created with .. autodecorator that are in fact supposed to be method-decorators.

[Lulalaby]

Cursed