Issue #78: Formatted docstrings to better utilize sphinx-apidoc

[johnowagon]

Description

Closes #XXX

Please include a summary of the changes and the related issue. Please also include relevant motivation and context. List any dependencies that are required for this change.

How should this pull request be reviewed?

• By commit
• All changes at once

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)

How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

• Unit tests (General Environment only) pytest --cov bsk_rl/envs/general_satellite_tasking --cov-report term-missing tests/unittest
• Integrated tests (General Environment only) pytest --cov bsk_rl/envs/general_satellite_tasking --cov-report term-missing tests/integration

Test Configuration

• Python: [3.10.1]
• Basilisk: [2.2.1]
• Platform: [OSX 12.6.6]

Checklist:

• My code follows the style guidelines of this project (passes Black, ruff, and isort)
  One check is unusually failing.
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• Commit messages are atomic, are in the form Issue #XXX: Message and have a useful message
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

This PR focuses on just formatting existing docstrings to be used by sphinx-apidoc in auto-generated documentation. I used the python package pydocstringformatter to perform these changes. There is no change in code.

When I was looking into this problem, I found a number of tools that can be used as commit checks like Black or Ruff to check docstring format (as i think the two linters do not support this at the moment). Should I go ahead and do that in this PR?

[Mark2000]

I like the changes that package made; looks like the only place it made black angry is an empty docstring, which probably shouldn't be there. Any rationale for https://github.com/DanielNoord/pydocstringformatter as opposed to the seemingly more popular https://github.com/PyCQA/docformatter ? Haven't used either before, just curious.

I do think we should add it as a commit check, whichever way we go.

[johnowagon]

No real reason, pydocstringformatter was the first package that I came across. docformatter looks more documented as well as more robust, so I think it would be best to use it from now on.

[johnowagon]

I looked into it a bit more and realized that ruff can be used for docstring linting, which is great because there is no need to add another github action. I added some rules for ruff to follow in the .ruff.toml, but they are a bit strict. Should I relax them a bit?

[Mark2000]

What are some examples of it possibly being too strict?

[johnowagon]

For one, it requires a docstring for every function. The ideal case for using this is if it would complain only on new code that doesn't have docstrings in new functions, but I'm not sure that ruff would work like that.

If you look at the details of the commit check, ruff finds 100+ functions without docstrings, which I think (?) it might highlight on every commit.

[Mark2000]

Yeah, I think we can have it ignore D101 and D102; the rest of it's complaints seem reasonable which what I can tell, though hard to see if it's flagging anything else weird in the sea of missing doctoring warnings.

[Mark2000]

oop, I missed that D103 is also one of those, can ignore that as well. How many of the remaining issues can ruff fix automatically?

[johnowagon]

Looking more into it I think ruff will only warn on errors, not actually fix them. I can look more into alternative solutions.