PR: Transform sorting functions from md to rst file

[steff456]

This PR rewrites the sorting functions markdown file in a rst file.

Ref: #283

[rgommers]

There's still an issue with the rendered docs:

signatures._sorting_functions. needs to go here.

[rgommers]

Looks like a nice start, thanks @steff456!

Just a note here that we had a discussion about type annotations and whether they should be reflected in the function signatures or not (this is controlled by autodoc_typehints, see https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html). We thought it's good to start with the doing both - our type annotations are very clean, so it hopefully will look good in signatures.

[asmeurer]

signatures._sorting_functions. needs to go here.

Do you mean the extra space after the ., or something else? The space is probably related to #139, which we will either have to fix by switching to another Sphinx theme or figuring out how to fix it upstream.

[kgryte]

@asmeurer I think he meant the entirety of signatures._sorting_functions. so that the spec just shows sort(...).

[steff456]

This PR is ready for review again!

Now the page of each function is shown like this,

[steff456]

With the latest changes, now the type hint for the return type is shown as the parameters and the Return type section is removed.

I think now this is ready!

[kgryte]

Based on the screenshot and looking through the changes, looks good to me.

[kgryte]

I think we can go ahead and merge this, and, if there are any further changes, we can address in follow-up PRs. Thanks, @steff456!