Improving the structure of the documentation and website

[janfb]

Our documentation has grown organically. During the March 2024 hackathon we made a lot of improvements on the content and currently we are working on improving the website accordingly, see #1147 .

However, I came across this guide: https://diataxis.fr/

I could be a good starting point for generally improving the structure of our documentation website. I think that's a bigger project, maybe something for the next SBI sprint / hackathon.

[janfb]

more sources for inspiration:

• https://estimagic.org/en/latest/
• https://pydvl.org/stable/

[evavanweenen]

Hi,

I'm a relatively low-level user of sbi and find it sometimes difficult to browse the API reference of the documentation. The point where I'm having most trouble is the link between code and documentation. I'm having trouble finding where to import something in my code if I see it in the API documentation and vice versa, I'm having trouble finding the documentation for something that I have imported in my code.

I'll write a few points below what I experienced and what could potentially be improved:

• For instance, if I want to look up the documentation for a trainer (NPE, NLE, etc.), it's not straightforward where to look in the documentation. The documentation for trainers is looked in the Inference part of the API documentation. In a similar example, the sbi.utils.process_prior function is under Inference in the documentation. Similarly, Posterior has its own heading in the documentation, but the posteriors are imported from sbi.inference.posteriors. Consistent naming would help here.
• It would also help a lot if the documentation followed the style of for instance pytorch, where you see the full path to the function and its arguments (e.g. torch.distributions.normal.Normal(loc, scale, validate_args=None) instead of Normal), so I know how to import this class/function in my code.
• The table of contents on the right-hand side could be cleaned up (e.g. removing private functions, merging init documentation with class documentation, sorting it).
• For some parts there is no documentation, for instance for the estimators. It would be great if there is documentation for all parts of SBI.

I think many suggestions could be relatively easily changed by changing settings from mkdocstrings (assuming that is what is used to build the documentation).

Thanks! :) (And so far I've really enjoyed using SBI.)

[janfb]

Hi @evavanweenen

thanks a lot for this feedback! This is very helpful. We will have a look at this at the hackathon in March.

[vagechirkov]

Hi there,

As a beginner SBI user, I sometimes find the documentation a bit frustrating. Personally, I believe adopting a scikit-learn style documentation approach would be incredibly helpful (e.g., https://scikit-learn.org/stable/api/index.html).

A few quick suggestions that could make a big difference:

• The tutorials and examples are excellent. However, they can't fully replace a dedicated "User Guide" section, which offers an overview of all functionality (similar to https://scikit-learn.org/stable/user_guide.html). Additionally, cross-referencing tutorials with the API references would make navigation much smoother.
• Having a centralized API reference rather than splitting it across multiple sections would significantly simplify navigation.
• Including short example snippets directly in the API documentation would help a lot to quickly understand specific functionalities.
• It would also be helpful if clicking "source" within the API docs took the user directly to the GitHub source code.

These are just my personal preferences, but I wanted to share them since I've found navigating the current API documentation challenging at times 🙃