Rule D417

[jamshale]

Updates function documentation to the appropriate level needed for rule D417 https://docs.astral.sh/ruff/rules/undocumented-param/. Helps developers understand and more quickly use functions if these are accurate.

Mostly used co-pilot to fill in wrong or missing arguments. Reviewed most of it and it looked like it was doing a good job.

[swcurran]

Way cool — that’s wild. And the config change means these will be kept up to date?

@jamshale — would you mind look at the warnings we are getting when we generate the read the docs? To see them:

• go into the docs folder
• Run the two instructions in the UpdateRTD.md file
  • The sphinx command to copy the latest set of files (e.g. rm -rf generated; sphinx-apidoc….)
  • The sphinx-build command

No worries if it is not obvious what is needed. Obvs, you need to install sphinx (or use docker) to run the commands.

FYI — I’m using version sphinx-build 5.3.0.

[jamshale]

Yes. It will at least fail the ruff lint check that is done with the unit tests and force developers to keep the function descriptions up to date. I think we should fully switch to ruff for linting, because right now ruff and black are both tools that can do the same thing. Ruff is just more popular now and faster. Not important to switch immediately, though.

I'll have a look at the doc warnings 👀

[dbluhm]

Full agreement from me on switching to ruff for formatting too; it is noticeably faster than black

[jamshale]

@swcurran Did you used to get any warnings or errors when running sphinx-build? I fixed one set of warnings related to these changes but am getting other warnings for unrelated documentation.

I can continue looking into them but might create another task for it. I'm having quite a bit of trouble trying to resolve them effectively.

[jamshale]

I'm slowly figuring out how to fix the sphinx errors and warnings. I'll include the changes in this PR once I resolve them all.

[swcurran]

Should you push that to another PR? Don’t want to take too much of your time on it.

[jamshale]

We can merge this the way it is. They warnings and errors only effect the individual docs. The rest will still be generated.

I think I should be done soon though. Fixed most of them.

[jamshale]

This is updated and should be good to go now.

[sonarcloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
92.8% Coverage on New Code
0.2% Duplication on New Code

See analysis details on SonarCloud