Build documentation with the --nitpicky option

[tovrstra]

This is one more step in the list in #313, and also a continuation of #333, just tightening the screws a little...

The --nitpicky option of Sphinx may seem nitpicking. However, when not switched on, Sphinx happily ignores broken references in the documentation. As a result, we had many of these. To clean things up, the configuration of sphinx extensions (for api documentation) also had to be improved. I've also gone through all NDArray type hints to specify them as float or int where this was applicable.

Summary by Sourcery

This pull request enhances the documentation build process by enabling the --nitpicky option in Sphinx, improving the configuration of Sphinx extensions, and updating type hints for NDArray to specify float or int where applicable. These changes ensure stricter validation of documentation references and improve type clarity.

• Enhancements:
  • Enabled the --nitpicky option in Sphinx to ensure all references in the documentation are valid, preventing broken references from being ignored.
  • Improved the configuration of Sphinx extensions for API documentation.
  • Updated type hints for NDArray to specify float or int where applicable, enhancing type clarity and correctness.
• CI:
  • Modified the Sphinx CI workflow to run with the --nitpicky option, ensuring that broken references are caught during continuous integration.
• Documentation:
  • Updated Sphinx build configuration to include the --nitpicky option, ensuring stricter validation of documentation references.

[sourcery-ai]

Reviewer's Guide by Sourcery

This pull request enables the --nitpicky option in Sphinx to ensure that all references in the documentation are valid. It also includes improvements to the Sphinx configuration for API documentation and updates to type hints for NDArray to specify float or int where applicable.

File-Level Changes

Files	Changes
iodata/formats/cp2klog.py iodata/iodata.py iodata/basis.py iodata/utils.py iodata/formats/cube.py iodata/overlap.py iodata/formats/wfn.py iodata/formats/fchk.py iodata/formats/chgcar.py iodata/formats/orcalog.py iodata/formats/gaussianlog.py iodata/formats/molden.py iodata/formats/qchemlog.py iodata/formats/gamess.py iodata/formats/molekel.py iodata/orbitals.py iodata/formats/mol2.py	Specified NDArray type hints to NDArray[float] and NDArray[int] where applicable.
iodata/docstrings.py iodata/api.py iodata/formats/json.py	Improved docstring descriptions for return values and attributes.
docs/conf.py .github/workflows/sphinx.yaml docs/Makefile docs/make.bat	Added --nitpicky option to Sphinx build commands and updated Sphinx configuration.

---

Tips

• Trigger a new Sourcery review by commenting @sourcery-ai review on the pull request.
• You can change your review settings at any time by accessing your dashboard:
  • Enable or disable the Sourcery-generated pull request summary or reviewer's guide;
  • Change the review language;
• You can always contact us if you have any questions or feedback.

[deepsource-io]

Here's the code health analysis summary for commits 6350b9e..e5c3179. View details on DeepSource ↗.

Analysis Summary

Analyzer	Status	Summary	Link
Shell	✅ Success		View Check ↗
Python	✅ Success		View Check ↗

---

💡 If you’re a repository administrator, you can configure the quality gates from the settings.

[sourcery-ai]

Hey @tovrstra - I've reviewed your changes and they look great!

Here's what I looked at during the review

• 🟡 General issues: 1 issue found
• 🟢 Security: all looks good
• 🟢 Testing: all looks good
• 🟢 Complexity: all looks good
• 🟢 Documentation: all looks good

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment to tell me if it was helpful.}

[PaulWAyers]

I didn't go through it in much detail but what I saw looked good to me.

[tovrstra]

Thanks for checking. There are indeed a lot of mechanical changes. The main goal is the change in the configuration files. All the nitty-gritty is just needed to make the tests pass (and fix links in the docs).