niksirbi commented 2 weeks ago

Description

What is this PR

[ ] Bug fix
[x] Addition of a new feature
[ ] Other

Why is this PR needed? Our API reference started getting a bit out of hand, as we add more and more functions and it's getting harder to find the functions you need at a glance. Moreover, when implementing a new function/class, one has to remember to always add it to the api_index.rst, which is easily forgotten. In some occasions this has resulted in new features being added without them appearing in the API index.

What does this PR do?

It overhauls the auto-documentation of API in some major ways:

the API reference homepage now shows a table of all public modules (see screenshot below). Each module's contents (functions/classes) are then recursively auto-generated. This means that we don't have to add the name of each function or class to the index, we just have to edit api_index.rst only when we add/rename modules (which happens much less often). Moreover, having the module table at the top level makes the index more hierarchically organised, making the relevant parts of the API docs more findable. Additionally, because now we have separate pages on the module level, we can easily reference an entire module from elsewhere in the docs (e.g. using :py:func:`movement.sample_data` in rst syntax). I've also sanitised the module-level docstrings, because now they're prominently displayed on the module table.

Screenshot from 2024-06-12 11-19-11

we now include some custom jinja templates for sphinx-autosummary, which are placed in docs/source/_templates/autosummary. Those enable us o implement the aforementioned recursive generation of index pages, but also allow us to fully control the appearance of classes/functions in the API index. This solves some of the problems mentioned in #178, but we can further customise them to our heart's content. @lochhh let me know if this is how you wanted classes to display, if not feel free to play with the class.rst template.
The page headings for individual functions/classes now only include the name of that object (e.g. MovementDataset) instead of the full "path" (e.g. movement.move_accessor.MovementDataset) which is often long and overflows to the right of the page. The full "path" is anyhow visible in the navigation bar (left) and in the signature of the object itself (below the header, see next screenshot). This was achiever via modifying the relevant jinja templates to display "name" instead of "fullname".

Screenshot from 2024-06-12 11-20-04

References

178

How has this PR been tested?

The docs were rendered and viewed locally. This is also the recommended way to review the PR.

Is this a breaking change?

No.

Does this PR require an update to the documentation?

It is in itself an update of documentation.

Checklist:

[x] The code has been tested locally
[ n/a ] Tests have been added to cover all new functionality
[x] The documentation has been updated to reflect any changes
[x] The code has been formatted with pre-commit

codecov[bot] commented 2 weeks ago

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 99.70%. Comparing base (2e406e1) to head (32d6c75).

Additional details and impacted files

```diff @@ Coverage Diff @@ ## main #213 +/- ## ======================================= Coverage 99.70% 99.70% ======================================= Files 12 12 Lines 678 678 ======================================= Hits 676 676 Misses 2 2 ```

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.