Add support for setting default value in type declaration for numpydoc, various fixes to numpydoc compose & unit tests.

[jwlodek]

See the parameters section of the numpydoc style guide for examples.

The ones provided there are:

copy : bool, default True
copy : bool, default=True
copy : bool, default: True

I've added support for all three cases. I added some checks to the unit tests to verify that this works, both for parsing and composition. I did find that the existing regex for finding defaults had some issues. For example:

defaults to 10

would return a default value of s, since the regex would match the "word" after default, which would be the character s. I fixed this original regex to account for this, and I added unit tests that test all the regexes for numpydoc parsing independently of the remaining classes, to double check their functionality.

---

Additionally, while working on this I also found a few issues test_numpydoc::test_compose test.

Essentially, the test was passing, but only because the input strings were not actually valid numpydoc docstrings, and thus did not match any of the regular expressions. The entire text was treated as a description, so it matched the expected output.

For example:

Short description

Meta:
------
    abcd

the metadata title should not have a colon at the end, and thus the underline should be one shorter. The abcd arg should also be shifted back a tab.

I modified the test inputs to be valid numpydoc, which then resulted in some failures due to the output of compose not matching what the test expected (mainly missing or too many newlines), which I fixed. Some test cases used Meta titles that were not in the default sections, which meant they were also being parsed as a description - I fixed this by making a custom parser with a few extra sections defined to cover these. To avoid this happening in the future, I also made a check to make sure that the parse operation was producing a docstring object with at least one Meta in the meta list, if expected.

The check is a bit primitive, and perhaps a better option would be to add an additional argument like meta_expected to each test case, but it works for the current test suite.

---

Finally, examples were not handled correctly in compose. Only the description was being added to the composed docstring, not the snippet (caught this once I fixed test_compose. I've also fixed that.

[mauvilsa]

Some comments from Codex. Not sure if they are true. But please have a look:

1. Potential crash in compose() when examples don’t start with >>>

   • In docstring_parser/numpydoc.py, compose() now appends example.snippet and example.description directly. If a Numpydoc Examples section begins with narrative text (no >>>), ExamplesSection.parse() yields DocstringExample(snippet=None, description="..."). That means parts.append(example.snippet) inserts None, and "\n".join(parts) will raise TypeError.
   • This is a real-world pattern in Numpydoc (explanatory lines before prompts).
   • Suggestion: guard before appending or coerce to "", e.g.:
     • Append only if example.snippet is not None.
     • Append example.description only if not empty.
   • Relevant code: docstring_parser/numpydoc.py (compose examples block).

2. Defaults found in descriptions won’t render unless is_optional is True

   • In compose(), the logic only emits , default=... when one.is_optional is true. But defaults found via PARAM_DEFAULT_REGEX_IN_DESC do not set is_optional anywhere.
   • Result: a docstring with arg : int and “Default: 10” in the description will parse a default but will not re-compose it, which is surprising given the new feature intent.
   • Suggestion: if a default is found in the description, consider setting is_optional = True in ParamSection._parse_item() or change compose() to add defaults when default is present regardless of is_optional.
   • Relevant code: docstring_parser/numpydoc.py in ParamSection._parse_item() and compose().

3. The new meta-check in tests is brittle

   • The test in docstring_parser/tests/test_numpydoc.py now checks if "-" in source: assert len(docstring.meta) > 0. That will fail for future test cases that contain hyphens in prose but no section header (a pretty plausible addition).
   • Suggestion: use the parser’s title regex (e.g., parser_w_meta_section.titles_re.search(source)) rather than a generic "-" check.
   • Relevant code: docstring_parser/tests/test_numpydoc.py near test_compose().

[jwlodek]

@mauvilsa I've addressed the issues that were brought up:

1. Added conditionals around adding example snippet/description to composition.
2. Reworked conditional for optional/default values in compose.
3. Reworked the test to pass the expected number of metas as an arg in the parametrization.

[jwlodek]

@mauvilsa would it be possible to make a new release version with this change sometime soon? I have a few projects I'd like to use it with. Thanks!