Summary
All four functions in philanthropy/metrics/_scoring.py — donor_retention_rate,
donor_acquisition_cost, cost_per_dollar_raised, fundraising_roi — have a
prose summary and a short explanatory paragraph, but none has a formal
Parameters or Returns section. The API reference is generated by
mkdocstrings from a bare ::: philanthropy.metrics directive, so each of
these four renders with its signature and the prose, but the arguments and
return value are not itemised the way every other metric in the package
documents them (see gift_concentration_gini or top_donor_share in
philanthropy/metrics/_concentration.py for the shape to copy).
This is a good first issue: no logic changes, and the prose already explains
the behaviour — the work is reformatting it into NumPy sections.
Where
| File |
Locate with |
philanthropy/metrics/_scoring.py |
grep -n "^def " philanthropy/metrics/_scoring.py |
What to change
NumPy format (mkdocs.yml sets docstring_style: numpy). For each of the four
functions, add:
Parameters — every keyword-only argument, one line each.
Returns — the value and, where the function has one, the np.inf sentinel
case already described in the existing prose (e.g. "np.inf when
new_donors_acquired is 0").
Keep the existing prose as the summary line(s) above the new sections; don't
delete the explanatory context, just add the missing structure around it.
Tests to add or extend
None — doc-only change, no new branch to cover.
Done when
python -c "
import inspect, sys, philanthropy.metrics as M
missing = [
n for n in ('donor_retention_rate', 'donor_acquisition_cost',
'cost_per_dollar_raised', 'fundraising_roi')
if 'Parameters' not in (getattr(M, n).__doc__ or '')
or 'Returns' not in (getattr(M, n).__doc__ or '')
]
print('MISSING:', missing or 'none'); sys.exit(1 if missing else 0)
" && echo OK
python -m pytest philanthropy --doctest-modules -q --no-cov
Summary
All four functions in
philanthropy/metrics/_scoring.py—donor_retention_rate,donor_acquisition_cost,cost_per_dollar_raised,fundraising_roi— have aprose summary and a short explanatory paragraph, but none has a formal
ParametersorReturnssection. The API reference is generated bymkdocstrings from a bare
::: philanthropy.metricsdirective, so each ofthese four renders with its signature and the prose, but the arguments and
return value are not itemised the way every other metric in the package
documents them (see
gift_concentration_giniortop_donor_shareinphilanthropy/metrics/_concentration.pyfor the shape to copy).This is a good first issue: no logic changes, and the prose already explains
the behaviour — the work is reformatting it into NumPy sections.
Where
philanthropy/metrics/_scoring.pygrep -n "^def " philanthropy/metrics/_scoring.pyWhat to change
NumPy format (
mkdocs.ymlsetsdocstring_style: numpy). For each of the fourfunctions, add:
Parameters— every keyword-only argument, one line each.Returns— the value and, where the function has one, thenp.infsentinelcase already described in the existing prose (e.g. "
np.infwhennew_donors_acquiredis 0").Keep the existing prose as the summary line(s) above the new sections; don't
delete the explanatory context, just add the missing structure around it.
Tests to add or extend
None — doc-only change, no new branch to cover.
Done when