Review formulary docstrings for equations and clarity
Open
Nobody has claimed this yet.
docs
good first issue
Plasma Lv2 | Intermediate
plasmapy.formulary
Python Lv1 | Beginner
refactoring ♻️
- Dominant language
- Python
- Stars
- 711
- Forks
- 375
- Avg merge
- 3h 2m
- Merged PRs (30d)
- 8
Description
The majority of the plasmapy.formulary docstrings are in good shape, but I still think there's room for improvement. Some functional docstrings are missing their associated formulae and some docstrings are difficult to read. I suggest we do the following...
- Add formulae to all
plasmapy.forumularyfunctionality where it is missing. (This should be a default requirement for all formualry items.) - Move/copy the formulae from the
Notessection to the main body of the docstring. This would move the equation to just below the function signature in the documentation, which would help with readability and understanding for users. - Review body, parameter, etc. descriptions for clarity. Keep in mind how these would read if you were new to them.
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 inventorying the docstrings under plasmapy.formulary and compare each function's main description with its Notes section. Review missing formulae and the clarity of body and parameter descriptions; the work is done when formulary functionality has the required equations in the main docstring and the descriptions have been revised for readability.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100