PlasmaPy / PlasmaPy/PlasmaPy

Create a script to inject standard parameter descriptions into docstrings

Open
#946 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

docs feature request priority: low Stale
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.