Re-organise API reference

[niksirbi]

Description

What is this PR

• Bug fix
• 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.

• 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 Fix auto-API formatting for the MovementDataset class #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".

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:

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

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 99.70%. Comparing base (7f6553b) to head (aa014b5).
Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #213   +/-   ##
=======================================
  Coverage   99.70%   99.70%           
=======================================
  Files          12       12           
  Lines         681      681           
=======================================
  Hits          679      679           
  Misses          2        2           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[lochhh]

This is great @niksirbi ! I have made some additional changes:

• prepended "_" to attrs validator functions to prevent these from showing up in the API docs
• changed "Parameters" headings to "Attributes" in movement/validators/files.py, in line with movement/validators/datasets.py
• added dim_names and var_names attributes to MovementDataset docstrings
• removed autosummary for attributes in class.rst. As the attributes appear immediately after the class description, there is no need for a summary table that only comes later.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarCloud