Auto-generate API index page

[lochhh]

Description

What is this PR

• Bug fix
• Addition of a new feature
• Other

Why is this PR needed?
Currently, one needs to manually update entries in the docs/source/api_index.rst page, so that new modules or renamed (existing) modules are included in the API reference. This PR automates the generation of this api_index.rst page using the make_api_index.py script, such that all modules are automatically included, except for what's specified in the exclusion list in this script.

What does this PR do?

• adds a make_api_index.py script and template api_index_head.rst for auto-generating the api_index.rst file
• because we need to execute this script, this PR also updates the Make files, such that Unix users can call from the docs/ directory (this is used in the build docs workflow)
  • make html instead of python make_api_index.py && sphinx-build source docs/build
  • make clean html instead of rm -rf [all auto-generated files] && python make_api_index.py && sphinx-build source build
  • make linkcheck instead of sphinx-build source build -b linkcheck
• updates the relevant documentation on the website
• uses the use-make input option of the NIU build_sphinx_docs and deploy_sphinx_docs actions in the build docs workflow to enable docs to be generated using the make utility
• removes the file api_index.rst and its tracking, as this is now auto-generated

How has this PR been tested?

Docs build successfully both locally and remotely. See also live docs on forked repo.

Does this PR require an update to the documentation?

I've updated the "API reference" section in CONTRIBUTING.md accordingly. For the "building docs locally" instructions, I've gone with the longer but more generic python docs/make_api_index.py && sphinx-build docs/source docs/build rather than the shorter make html as the command would be different for windows vs Unix users. make is also not necessarily available on all systems and may require additional installation. Let me know your thoughts on this.

TODO:

• Revert changes in build docs workflow (pending actions repo PR approval)

Checklist:

• The code has been tested locally
• 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.74%. Comparing base (d943b29) to head (57b8282).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #234   +/-   ##
=======================================
  Coverage   99.74%   99.74%           
=======================================
  Files          13       13           
  Lines         771      771           
=======================================
  Hits          769      769           
  Misses          2        2           

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

[sfmig]

looks great! 🚀

Make is out of my depth but I made a couple suggestions. But everything works well locally for me ✨

[niksirbi]

Very nice work @lochhh! I guess it makes sense to first merge the actions PR, modify this one accordingly and then follow up with merging this one?

[niksirbi]

Is there any way we can define a custom ordering of modules, if we wish to ever override the default alphabetical ordering?

On one hand having a custom order would allow us to highlight the "important" modules near the top. But on the other hand, having that custom step will introduce manual work when creating/deleting a module, and the whole point of this PR was to eliminate manual work. So I think I'm fine with this staying alphabetical.

What do you think?

[niksirbi]

I've merged the proposed upstream change in actions and release actions v2.6.0 (latest). This PR should be good to proceed now @lochhh

[niksirbi]

Thanks @lochhh!
I just had two final comments.

[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