Refactor auto-generate API docs

[lochhh]

Description

What is this PR

• Bug fix
• Addition of a new feature
• Other

Why is this PR needed?
closes #329

What does this PR do?
This PR

• simplifies the code for auto-generating API docs
• adds the clean action and enables the fail-on-warnings mode for Sphinx (-W) in the Windows make.bat to match the Unix Makefile
• drops the unused --keep-going for Sphinx (as it is automatically enabled from Sphinx 8.1)
• updates the "build docs" documentation
• removes the Sphinx version constraint in requirements.txt

References

#329

How has this PR been tested?

Local docs build

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.76%. Comparing base (1b6b44d) to head (bb6437c).
Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #331   +/-   ##
=======================================
  Coverage   99.76%   99.76%           
=======================================
  Files          14       14           
  Lines         846      846           
=======================================
  Hits          844      844           
  Misses          2        2           

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

[niksirbi]

Looks good @lochhh!

Just two questions for you:

• Do the changes in make.bat also enable a simpler syntax for building the docs on Windows? If yes, the contributing guide should be updated accordingly.
• should we constrain sphinx>=8.1 in the docs requirements?

[lochhh]

• Do the changes in make.bat also enable a simpler syntax for building the docs on Windows? If yes, the contributing guide should be updated accordingly.

Thanks for spotting this. That's done. Feel free to suggest better names than "make mode" and "Default mode". I've also simplified the rebuild instructions by providing only the clean command and redirecting users back "to the build command above" for rebuilding. I couldn't decide between using a nested tab-set for the Unix, Windows clean commands or keeping both in the same tab-item, and have decided to go with the former. Lmk if you prefer the latter.

• should we constrain sphinx>=8.1 in the docs requirements?

I've removed the constraint completely.

[niksirbi]

1. Radical solution: do we even need to mention the "default mode"? The syntax is much clunkier there, and if we get rid of it, we will no longer have a need for nested tabsets - which I don't particularly like. Also we no longer have to come up with names for the "modes".

2. Something seems to have gone wrong with the rendering of monospace in make:
   

3. I would also add that one can combine multiple make commands for convenience. For example, make clean html linkcheck will do everything for you.

[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

[niksirbi]

This looks good now @lochhh, shall we merge it?

[lochhh]

This looks good now @lochhh, shall we merge it?

Done. Thanks for taking a final look!