Skip to content

[DOC] ASR: fix numpydoc docstring rendering#119

Open
sappelhoff wants to merge 1 commit into
nbara:masterfrom
sappelhoff:fix/asr-docstring-rendering
Open

[DOC] ASR: fix numpydoc docstring rendering#119
sappelhoff wants to merge 1 commit into
nbara:masterfrom
sappelhoff:fix/asr-docstring-rendering

Conversation

@sappelhoff

Copy link
Copy Markdown
Collaborator

Three malformed numpydoc constructs in meegkit/asr.py rendered incorrectly in the Sphinx API docs.

1. clean_windows parameter list mangled

A free-text paragraph sat inside the Parameters block. numpydoc parsed each line as a name (type) entry, producing four garbage "parameters" and disrupting the real ones:

tuned. (The following are detail parameters that usually do not have to be)
want (If you can't get the function to do what you)
consider (you might)
data. (adapting these to your)

Moved that guidance to a Notes section; all documented parameters now render correctly.

2. ASR attribute names showed literal backticks

Attributes wrapped names in double backticks (``zi_``, ``ab_``, ``cov_``, ``state_``), so the backticks appeared verbatim in the rendered headings. Changed to plain zi_ : array, ....

3. cutoff: missing space before colon

cutoff: (in ASR and asr_calibrate) is not valid numpydoc name : type syntax. Changed to cutoff : float.

Verification

  • Built the API docs before/after: all parameters and attributes render correctly, no build warnings.
  • Added a regression test (test_docstring_parameters, test_docstring_attributes) that parses the docstrings with numpydoc; it fails on the original docstrings and passes after the fix.
  • Full tests/test_asr.py passes; ruff clean.

Three malformed numpydoc constructs rendered incorrectly in the Sphinx
API docs:

- clean_windows had a free-text paragraph inside the Parameters block,
  which numpydoc parsed as four garbage "parameters" (tuned., want,
  consider, data.); moved it to a Notes section.
- ASR Attributes wrapped the names in double backticks (``zi_`` etc.),
  so the literal backticks showed in the rendered attribute headings.
- cutoff in ASR and asr_calibrate used "cutoff:" (no space before the
  colon), which is not valid numpydoc name/type syntax.

Add a regression test that parses the docstrings with numpydoc and
checks that documented parameters match the signature and attribute
names carry no markup.
@codecov

codecov Bot commented Jul 13, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 83.10%. Comparing base (3721224) to head (b6c82d0).

Additional details and impacted files
@@           Coverage Diff           @@
##           master     #119   +/-   ##
=======================================
  Coverage   83.10%   83.10%           
=======================================
  Files          25       25           
  Lines        2818     2818           
=======================================
  Hits         2342     2342           
  Misses        476      476           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@sappelhoff sappelhoff mentioned this pull request Jul 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant