docs: improve NumPy-style docstrings for API reference

[AlgoFoe]

Description

What is this PR

• Bug fix
• Addition of a new feature
• Other

Why is this PR needed?

• The codebase lacked consistent docstrings, making Sphinx autodoc output incomplete and hard to read.

What does this PR do?

• Adds/updates NumPy-style docstrings (module, class, method, function level) across actor.py and atlas.py.

References

• Issue-96

How has this PR been tested?

• No functional changes, existing tests pass.

Is this a breaking change?

• No.

Does this PR require an update to the documentation?

• Yes.

Checklist:

• The code has been tested locally
• Tests have been added to cover all new functionality (unit & integration)
• 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 88.22%. Comparing base (40346b5) to head (a926b85).
⚠️ Report is 3 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #451      +/-   ##
==========================================
- Coverage   89.37%   88.22%   -1.16%     
==========================================
  Files          27       27              
  Lines        1280     1282       +2     
==========================================
- Hits         1144     1131      -13     
- Misses        136      151      +15     

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

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[AlgoFoe]

The failing CI job looks unrelated to the docstring changes (atlas download timeout). I'll continue updating the remaining modules in this.

[adamltyson]

Yep, we're having ongoing issues with our hosting until we complete the move to AWS.

[alessandrofelder]

Thanks @AlgoFoe - this is a great start.

My one general comment is: should we add typehints to the functions' input arguments and return values as we document them? I think this would add a lot of value for not that much work (we need to figure out the types for the docstrings anyway)?

Otherwise, I've made some nitpicky suggestions for improvements :) (You are welcome to disagree with them if you think I got something wrong - this happens (a lot 😁 ))

[AlgoFoe]

My one general comment is: should we add typehints to the functions' input arguments and return values as we document them? I think this would add a lot of value for not that much work (we need to figure out the types for the docstrings anyway)?

That's a good idea. Since we're already working out the types, adding type hints alongside the updates could be a nice incremental improvement. I'll have a look and see how much of that can reasonably be incorporated as I work through the modules.

[alessandrofelder]

I'll have a look and see how much of that can reasonably be incorporated as I work through the modules.

Cool, let me know what you find. My hope is that it can be part of the docstring writing process itself so we don't have to look at the same code twice :)

[AlgoFoe]

Cool, let me know what you find. My hope is that it can be part of the docstring writing process itself so we don't have to look at the same code twice :)

I've added type hints and addressed the suggested docstring changes and will apply the same approach in future updates after this.

[alessandrofelder]

Thanks @AlgoFoe - this looks great. One final (annoying, sorry, but at least simple and very impactful!) requested could you explore using sphinx-autodoc-typehints, please, and remove types from the docstrings for the input arguments. This should autogenerate the type in the sphinx-docs and avoid the docstring type and the function typehint going out of sync. This will be very helpful work.

Looking at how movement does it might help

[AlgoFoe]

No worries at all, I wasn't aware of sphinx-autodoc-typehints before this 😅. I'll have a look at how movement is using it and update the PR

[AlgoFoe]

I had a quick look at sphinx-autodoc-typehints locally, and it seems promising, I have also updated the docstrings with the suggested changes. We'll probably need to make a few updates to conf.py and some other files later on to integrate it properly into the documentation.

[alessandrofelder]

Nice one, thanks @AlgoFoe