Patch for NumpyDocString to add more parameter supported classes

[s01st]

At present docscrape.NumpyDocString finally supports all Numpy Document Sections. However, only the Parameters section supports parameters. However per numpydoc many sections should support parameters e.g. Attributes.

This patch:

1. Adds a constant PARAM_SECTIONS to note sections which support parameters.

2. Updates NumpyDocString to:

   • include a param_sections similar to sections,

   • normalize the parameter processing done for NumpyDocString.sections['Parameters'] to the supported param_sections,

   • exposes configuration options to NumpyDocString.__init__

At present, this will prevent complaints when running nbdev_prepare due to TypeErrors. For example, consider the simple class:

#| export
@dataclass
class Message:
    """A single message in a conversation.
    
    Attributes
    ----------
    role : Literal["system", "user", "assistant"]
        The role of the message sender
    content : str
        The message content
    timestamp : datetime
        When the message was created
    metadata : dict
        Additional metadata (e.g., token count, model info)
    
    Examples
    --------
    >>> msg = Message(role="user", content="Hello!")
    >>> msg.role
    'user'
    """

Then:

> showdoc.parse_docstring(Message)

---------------------------------------------------------------------------
TypeError                                 Traceback (most recent call last)
Cell In[9], [line 70](vscode-notebook-cell:?execution_count=9&line=70)
     69 parsed_data = copy.deepcopy(sections)
---> [70](vscode-notebook-cell:?execution_count=9&line=70) docscrape.NumpyDocString(docstring(Message))
     71 showdoc.parse_docstring(Message)

File ~/mamba/envs/fastcore_env/lib/python3.12/site-packages/fastcore/docscrape.py:112, in NumpyDocString.__init__(self, docstring, config)
    110 self['Parameters'] = {o.name:o for o in self['Parameters']}
    111 if self['Returns']: self['Returns'] = self['Returns'][0]
--> [112](https://file+.vscode-resource.vscode-cdn.net/Users/demo_user/Projects/NBDev_Example/nbs/doctest/~/mamba/envs/fastcore_env/lib/python3.12/site-packages/fastcore/docscrape.py:112) for section in SECTIONS: self[section] = dedent_lines(self[section], split=False)

File ~/mamba/envs/fastcore_env/lib/python3.12/site-packages/fastcore/docscrape.py:235, in dedent_lines(lines, split)
    233 def dedent_lines(lines, split=True):
    234     """Deindent a list of lines maximally"""
--> [235](https://file+.vscode-resource.vscode-cdn.net/Users/demo_user/Projects/NBDev_Example/nbs/doctest/~/mamba/envs/fastcore_env/lib/python3.12/site-packages/fastcore/docscrape.py:235)     res = textwrap.dedent("\n".join(lines))
    236     if split: res = res.split("\n")
    237     return res

TypeError: sequence item 0: expected str instance, Parameter found

After applying the patch:

> showdoc.parse_docstring(Message)

{ 'Also': '',
  'Attributes': 'role\ncontent\ntimestamp\nmetadata',
  'Examples': '>>> msg = Message(role="user", content="Hello!")\n'
              '>>> msg.role\n'
              "'user'",
  'Extended': '',
  'Methods': '',
  'Notes': '',
  'Other': '',
  'Parameters': {},
  'Raises': '',
  'Receives': '',
  'References': '',
  'Returns': [],
  'See': '',
  'Summary': 'A single message in a conversation.',
  'Warnings': '',
  'Warns': '',
  'Yields': ''}

[s01st]

@jph00 is this good to go?

[jph00]

Thanks for the contribution. It's a bit hard to review at the moment since it's so verbose and out of line with fastai style. Please try to keep it consistent with existing coding style, remove TODOs if you're not doing them (or else do them), and remove comments that aren't definitely needed to explain unusual special cases. Keep things clear and concise.

[jph00]

This is unrelated to the PR - move to separate PR if needed.

[s01st]

@jph00 , I removed the comments, but I don't think the changes were that verbose...

re: parallel, the issues are superficially related since they affect my capacity to run nbdev_prepare...
Though I think I fixed it and made a new PR

[s01st]

@jph00 so multiprocessing is now on its own PR and this is cleaner for just the docstring stuff

[jph00]

Thanks for the improvements. Still a bit to do to get things more concise. Also remember the notebooks are the source, not the .py. Be sure to use the notebooks fully to take the reader through what's happening.

[s01st]

@jph00 I know that notebooks are source of truth.... but not all files come from notebooks? e.g. docscrape.py. Is this part of a larger migration plan?

If so, I love working in nbdev and am happy to assist with that. I actually made an nbdev MCP that has been quite a quality of life improvement. I know that nbdev-index seems to be making its way into more things...

[jph00]

Many thanks for the style fixups. Looking good!

And sorry, I totally forgot there isn't a notebook for docscrape. I suspect what happened is I borrowed the code from somewhere else and didn't get around to nb'ing it. Yes if you're open to doing that, that would be cool - we could then have some nice docs and stuff.

I'd love to see your MCP BTW if you're open to sharing.

[s01st]

@jph00 re: notebook-ify. Separate branch for the pr then? or continue here?
re: mcp, sure. What is the best way to share?

[jph00]

Separate branch for the PR :)

Stick your MCP thing in a github repo and share the URL here!