AnswerDotAI / AnswerDotAI/nbdev

Presence of `Raises` section on Numpy docstring causes obscure error when compiling docs

Open
#1,506 0 comments 0 reactions 0 assignees View on GitHub
bug
Dominant language
Jupyter Notebook
Stars
5.3k
Forks
513
Avg merge
2d 30m
Merged PRs (30d)
8

Description

If a docstring is in Numpy format and contains a `Raises` section, which is [part of the standard](https://numpydoc.readthedocs.io/en/stable/format.html#raises), the [quarto-ghp](https://github.com/AnswerDotAI/workflows/tree/master/quarto-ghp) GitHub Action crashes with an obscure error and long traceback.

The key part of the error is this:
```
File "/opt/hostedtoolcache/Python/3.12.9/x64/lib/python3.12/site-packages/fastcore/docscrape.py", line 112, in __init__
for section in SECTIONS: self[section] = dedent_lines(self[section], split=False)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/opt/hostedtoolcache/Python/3.12.9/x64/lib/python3.12/site-packages/fastcore/docscrape.py", line 235, in dedent_lines
res = textwrap.dedent("\n".join(lines))
^^^^^^^^^^^^^^^^
TypeError: sequence item 0: expected str instance, Parameter found
```

Here's a MWE docstring:
```
"""Do something.

Does some stuff.

Parameters
----------
a : str
A string argument.
b : int, optional
An optional integer argument.

Raises
------
ValueError
If something is wrong with the provided parameters.
"""
```

Removing the `Raises` section solves the error, but it took a while to track down that this was the issue.

I know the preferred documenting format for nbdev is docments, but sometimes contributors write Numpy-style docstrings. It would be nice to avoid `Raises` sections from breaking the doc generation, or at least provide a more helpful error message.

Note that running `show_doc` manually in the notebook results in a `UserWarning`, so I don't understand why in the Action generates an exception.

I'm not sure exactly where the fix for this belongs (e.g. fastcore, workflows, ...), so starting by posting it here. The fix isn't urgent, but hopefully documenting this issue will help others who encounter it.

Many thanks to the nbdev team for providing such a valuable tool!

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.