Skip to content

ENH: add GL11 validation for bullet list formatting in docstrings#693

Open
Sidra-009 wants to merge 4 commits into
numpy:mainfrom
Sidra-009:gl11-bullet-list-check
Open

ENH: add GL11 validation for bullet list formatting in docstrings#693
Sidra-009 wants to merge 4 commits into
numpy:mainfrom
Sidra-009:gl11-bullet-list-check

Conversation

@Sidra-009
Copy link
Copy Markdown

this PR introduces GL11 validation to detect missing blank lines before bullet lists in docstrings

this prevents a known Sphinx Napoleon rendering issue where bullet lists are incorrectly merged into paragraphs when not separated by a blank line after a colon.

the check triggers when:

  • A line ends with ":"
  • The next line starts with a bullet (-, * or +)
  • No blank line exists between them

this improves docstring rendering consistency and documentation quality

Copy link
Copy Markdown
Collaborator

@larsoner larsoner left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you update a test that would fail on main but pass on this PR?

I think it would show that this is not working yet, as I tried it on a repo and got:

____________________________________________________________________________ test_docstring_parameters _____________________________________________________________________________
mne/tests/test_docstring_parameters.py:190: in test_docstring_parameters
    incorrect += check_parameters_match(method, cls=cls, where=name)
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
mne/tests/test_docstring_parameters.py:131: in check_parameters_match
    for err in validate(name)["errors"]
               ^^^^^^^^^^^^^^
../numpydoc/numpydoc/validate.py:755: in validate
    errs.append(error("GL11"))
                ^^^^^^^^^^^^^
../numpydoc/numpydoc/validate.py:219: in error
    return code, ERROR_MSGS[code].format(**kwargs)
                 ^^^^^^^^^^^^^^^^
E   KeyError: 'GL11'

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.

2 participants