[WIP] Documentation update

[AntObi]

Summary

In the API reference of the current documentation for atomate2, not all of the subpackages and modules are displayed, which means that a new user to atomate2 will not be able to see all the new workflows added (e.g. forcefields, CP2K etc).

• Fix 1: Add new subpackages to index.rst to update the documentation

TODO (if any)

• Updating index.rst adds the subpackages to the API reference, but not all subpackages have been automatically documented correctly (see image above). I need to investigate the cause of this.
• Need to document that when developers create a new subpackage, they should also add it to the index.rst file and also check that the documentation renders properly locally.

Checklist

Work-in-progress pull requests are encouraged, but please put [WIP] in the pull request
title.

Before a pull request can be merged, the following items must be checked:

• Code is in the standard Python style.
  The easiest way to handle this is to run the following in the correct sequence on
  your local machine. Start with running ruff and ruff format on your new code. This will
  automatically reformat your code to PEP8 conventions and fix many linting issues.
• Doc strings have been added in the Numpy docstring format.
  Run ruff on your code.
• Type annotations are highly encouraged. Run mypy to
  type check your code.
• Tests have been added for any new functionality or bug fixes.
• All linting and tests pass.

[utf]

Thanks very much @AntObi for the detailed PR. I'm happy to merge once the CI passes. I think the main issue is the punctuation that was removed.

To make things easier, you can install the pre-commit which will catch most things before committing.

pip install pre-commit
pre-commit install

[AntObi]

@utf Thanks for the fast response! You can hold off on merging this PR until I fix the issue with the forcefields subpackage not showing all of the available modules!

[JaGeo]

Great work, @AntObi ! Wondering if we should also update the readme?

[AntObi]

Hi @utf @JaGeo , I think this PR will take longer than I expected 😅 .

TODO (if any)

• Updating index.rst adds the subpackages to the API reference, but not all subpackages have been automatically documented correctly (see image above). I need to investigate the cause of this.
• Need to document that when developers create a new subpackage, they should also add it to the index.rst file and also check that the documentation renders properly locally.

As I mentioned in the TODO for this PR, some of the subpackages/modules don't have their classes and functions appear in the docs. So far, I haven't been identify the cause of this (likely something I have to dig into Sphinx to find out).

@JaGeo What did you have in mind for updates to the README?

[utf]

Hi @AntObi. All you should need to do is add the top level links. Sphinx-autodoc should do the rest. Can you try removing the build folder and rebuilding from scratch. Does that help at all?

[JaGeo]

@JaGeo What did you have in mind for updates to the README?

Similar to the publication draft, we could list all available calculators and highlight the most important workflows.