GitHub action for docs

[tovrstra]

This will build the documentation for IOData in a GitHub Action, using the new GitHub Pages deployment feature. (It no longer requires a github-pages branch, so we can remove it after this PR is merged.)

Preview on my repo: https://tovrstra.github.io/iodata/index.html

In addition to adding a file .github/actions.sphinx.yaml, the following changes were made:

• The sphinx conf.py file was recreated from scratch, by following the Sphinx getting started documentation. Or conf.py seemed to contain outdated stuff, which was hard to get right.
• The script gendocs.sh is replaced by corresponding code in conf.py. The gen_*.py scripts have been updated accordingly.
• Class attributes now have their own docstrings. This is supported (and somewhat imposed) by sphinx autodoc. This change was required to solve all warnings and errors while building the documentation. It also makes it easier for humans to read and write these docstrings while working on the code. The resulting documentation also becomes easier to process (redundancy).
• The Furo Sphinx theme is used instead of the RTD theme. Furo looks a lot better and is for that reason also very popular. (It supports light and dark mode.)
• Renamed doc/ to docs/, which is more common. This makes it easier to borrow snippets from other GitHub projects.
• Fixed (code) typos when I saw them. (attrs, Iterable, ...)
• All examples from our "Getting started" are put into Python files, which get tested by Pytest. This makes sure our examples don't fail with an error message. (I have updated them where relevant.)
• Added links to API documentation in our "Getting started"

I will YOLO-merge this on Friday, June 14 unless reviewed earlier.

See #313 for the bigger picture.

Summary by Sourcery

This pull request introduces a GitHub Action to build and deploy documentation using GitHub Pages, updates the Sphinx configuration and generation scripts, switches the Sphinx theme to Furo, and renames the doc/ directory to docs/. It also fixes various code typos, updates class attributes for better documentation, and adds tests for example scripts.

• New Features:
  • Introduced a GitHub Action to build and deploy documentation using GitHub Pages.
  • Added new Sphinx configuration and generation scripts for documentation.
  • Implemented new example scripts for generating Gaussian input files and converting file formats.
• Bug Fixes:
  • Fixed various code typos and updated class attributes to have their own docstrings to resolve Sphinx autodoc warnings and errors.
• Enhancements:
  • Replaced the gendocs.sh script with corresponding code in conf.py.
  • Updated gen_*.py scripts to align with the new documentation generation process.
  • Switched the Sphinx theme from RTD to Furo for better aesthetics and support for light and dark modes.
  • Renamed the doc/ directory to docs/ for consistency with common conventions.
• CI:
  • Added a new GitHub Actions workflow (sphinx.yaml) to automate the building and deployment of documentation.
• Documentation:
  • Recreated the Sphinx conf.py file from scratch to follow the latest Sphinx documentation guidelines.
  • Updated the documentation to include links to API documentation in the 'Getting Started' section.
  • Ensured all examples from the 'Getting Started' guide are now tested with Pytest to prevent errors.
• Tests:
  • Added tests to ensure that example scripts run without errors.

[deepsource-io]

Here's the code health analysis summary for commits df4c5ab..e424cf6. View details on DeepSource ↗.

Analysis Summary

Analyzer	Status	Summary	Link
Shell	✅ Success		View Check ↗
Python	❌ Failure	❗ 2 occurences introduced 🎯 7 occurences resolved	View Check ↗

---

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

[sourcery-ai]

Reviewer's Guide by Sourcery

This pull request introduces a GitHub Action to build and deploy the documentation for IOData using GitHub Pages. It includes significant changes to the Sphinx configuration, documentation structure, and codebase to support this new workflow.

File-Level Changes

Files	Changes
iodata/iodata.py iodata/basis.py iodata/orbitals.py iodata/utils.py	Replaced inline docstrings with attribute-level docstrings and updated class attributes to use attrs.field with appropriate validators and converters.
docs/conf.py docs/gen_formats.py docs/gen_inputs.py docs/make.bat docs/example_scripts/write_gaussian_com_custom.py docs/example_scripts/write_gaussian_com_template.py docs/example_scripts/test_scripts.py docs/example_scripts/convert_fchk_xyz_traj_mod2.py docs/_static/css/table.css docs/example_scripts/convert_fchk_xyz_traj_mod1.py docs/example_scripts/write_gaussian_com_file.py docs/example_scripts/data_representation.py docs/example_scripts/write_gaussian_com_lot.py docs/example_scripts/convert_fchk_molden.py docs/example_scripts/load_trajectory.py docs/example_scripts/load_water.py docs/example_scripts/load_water_foo.py docs/example_scripts/my_template.com	Added new Sphinx configuration, scripts, and example files for building and deploying documentation.
doc/conf.py doc/gen_formats.py doc/gen_inputs.py doc/_static/css/override.css doc/.readthedocs.yaml doc/gen_docs.sh	Deleted old Sphinx configuration, scripts, and CSS files.

---

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.

[sourcery-ai]

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

Here's what I looked at during the review

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

---

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.}

[tovrstra]

@sourcery-ai review

[sourcery-ai]

We have skipped reviewing this pull request. It looks like we've already reviewed this pull request.

[PaulWAyers]

OK by me. We started using a lot more JupyterBook for documentation, as that seems sort of seamless (it's what GQCP uses too).

Given the "history" of IOData with Sphinx, though, I think this is a good choice.

[tovrstra]

Thanks for the suggestion. I'll definitely check out JupyterBook. It seems interesting, but it is indeed quite a bit of work to convert all the documentation.

[tovrstra]

For future reference, the documentation can now be found at the following URLs:

• Built by GitHub Action: https://iodata.qcdevs.org/
• Built by Read The Docs: https://iodata.readthedocs.io/

[tovrstra]

I've also removed the preview on my tovrstra repository.