Structure API reference: individual pages and overview tables

[hildeweerts]

Describe the issue linked to the documentation

The current format puts the documentation of all functions/classes of a module on a single page. As the pages are getting quite long and often contain different types of functionality (e.g., "base" metrics versus fairness metrics in the metrics module), it can be difficult to get a good overview of the available functionality. This also makes it harder than necessary to find the documentation of a particular function/class.

Suggest a potential alternative/fix

I'd suggest to list the functions/classes in tables with a short description of each item. We can put the actual documentation on a separate page for each function/class. We can put all tables on a single page, similar to scikit-learn or on a separate page for each module, similar to pandas. My personal preference would go to the latter.

[Adapted from larger issue #601]

[adrinjalali]

I obviously prefer the first suggestion but I'm biased :P I'm happy either way.

[hildeweerts]

@fairlearn/fairlearn-maintainers do any of you have a preference for either pandas or scikit-learn format?

[riedgar-ms]

So long as everything happens automatically, I'm not fussed.

[hildeweerts]

@riedgar-ms it depends a bit on what you mean with automated, I believe these solutions are actually not 100% automated, because you have to create the table with instructions and such (not sure though, I don't have a ton of experience with sphinx). However, I don't think we are adding new classes, etc. that often so maintenance-wise it shouldn't result in much overhead after the initial set up.

[romanlutz]

I think creating pages per module is nice and simple (and consistent with what we're doing so far, not that that should matter...). It's not a hill I'm willing to die on, though, so either way is fine.

The overall idea with overview tables is fantastic and I'm wholeheartedly in support. :-)

[adrinjalali]

Not sure if it's related to this one, but one reason I prefer single page docs is that when I go here, I don't even know how many items are there. It's quite confusing. This could be mitigated with another list on the right side maybe which would show the ToC of the page, cc @riedgar-ms

[romanlutz]

I don't know how hard it is to add the list on the right side since that depends mostly on the pydata sphinx theme. We can certainly move to separate pages, though, just like

• sklearn: https://raw.githubusercontent.com/scikit-learn/scikit-learn/main/doc/modules/classes.rst
• pandas: https://github.com/pandas-dev/pandas/tree/master/doc/source/reference

[romanlutz]

A first step would be to also enable the "right sidebar"

https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/sections.html#the-right-in-page-sidebar

[shimst3r]

Let me help. :)

[romanlutz]

@shimst3r go ahead 🙂

[shimst3r]

@romanlutz if I understand the pydata sphinx documentation correct, I have to add a my own template for this, as this issue points out there is no way of generating TOC items from functions etc. at the moment.

Any opinions how this should look like? 😄

[romanlutz]

You're not trying to change the layout I think, but rather to split pages into more pages and have overview pages. Correct me if I'm wrong!

That means you might be fine with just using another layer of index.rst per module (?)

It may be a good idea to compare with scikit-learn which already does what @hildeweerts is looking for. I'll try and check but may not get to it this week.

[shimst3r]

Let me ping this to make clear I'm still on it, just didn't find the time to actually work on it. 😅

[hildeweerts]

@shimst3r any chance you've found some time to work on this?

As we're adding examples (e.g., #944) I think having individual pages becomes even more important!

[hildeweerts]

Closing in favor of #1174