DOC Split out API reference docs

[alliesaizan]

Describe the issue linked to the documentation

Currently, the API docs for each module include all the components of that module on one page, as shown below:

Suggest a potential alternative/fix

Suggest splitting the docs up so that each component in the module gets its own page, like in the image below:

This issue was brought up during the weekly community call on 1/12/23, and I found a package that can automatically split up Sphinx docs, sphinx-audomodapi.

Looping in @hildeweerts @MiroDudik @romanlutz to see if this package would work for this use case (also @hildeweerts, let me know if I misinterpreted the issue you mentioned!). I'd be happy to research this more and submit a PR if you think this would be a good solution!

[romanlutz]

I checked what scikit-learn does for this since they have exactly what we want in a working state. I think I got something promising with just "autosummary". I pushed it to a little branch. Feel free to build on that if you want! https://github.com/fairlearn/fairlearn/tree/romanlutz/separate_page_per_class_and_func
[Sorry for pushing the branch to the main repo, that was a mistake, but I guess it'll work....]

[alliesaizan]

Oh np, autosummary was another way I saw to do this! If that's working then I will close this issue :)

[romanlutz]

TBH I don't know about pros and cons of each option. autosummary just looks pretty straightforward and staying in somewhat close alignment with scikit-learn is typically a good idea as we can keep adopting their innovations 🙂 Let's leave the issue open until a PR is out and merged (?)
I'll leave it up to you whether you want to try this or not. If not, I might be able to try it over the next few weeks, but no guarantee.

[hildeweerts]

This is exactly the issue I was referring to @alliesaizan!

About a million years ago I opened an issue for this #720, I will close that one in favor of this new issue.

[alliesaizan]

TBH I don't know about pros and cons of each option. autosummary just looks pretty straightforward and staying in somewhat close alignment with scikit-learn is typically a good idea as we can keep adopting their innovations 🙂 Let's leave the issue open until a PR is out and merged (?) I'll leave it up to you whether you want to try this or not. If not, I might be able to try it over the next few weeks, but no guarantee.

Gotcha, I will apply the autosummary method to all the modules and send a PR!

[romanlutz]

This looks like it's completed. @hildeweerts can you close if you agree? This technically goes all the way back to #455 so I want to make sure it's addressed in a way that's consistent with your expectations 🙂

[hildeweerts]

Similar to @adrinjalali I'm not a huge fan of listing everything on the left hand side, but we can look into that in the future if it's really bothering people. Will close this issue!