Create a script to inject standard parameter descriptions into docstrings
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 711
- Forks
- 375
- Avg merge
- 3h 2m
- Merged PRs (30d)
- 8
Description
There are a whole bunch of functions in plasmapy.formulary and plasmapy.particles that have the same arguments. Because they have the same arguments, they should have the same description in the Parameters section of the docstring. But they don't. If we want to standardize them, then right now we would have to copy and paste the same thing in every function that uses them. If we want to change the standard description, then we would have to make the change in every docstring that they appear in.
One possibility that we thought about was to create a decorator akin to @modify_docstring in #908 that would inject the standardized parameter descriptions into the docstrings during import. However, this could slow down imports, and the docstrings in the files would not contain the parameter descriptions.
An alternative solution would be to create a script that goes through each of the requested files, looks for functions and methods that take in standard arguments like B, n_e, and ion, and then inject the standardized docstring directly into the module file, which would then be committed.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing the existing @modify_docstring approach referenced in issue #908, then inspect functions and methods in plasmapy.formulary and plasmapy.particles that use standard arguments such as B, n_e, and ion. Define how the script identifies those arguments and their standard descriptions. Done means the requested module files contain consistent, committed parameter descriptions without requiring runtime docstring injection.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation, tooling
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100