AnswerDotAI / AnswerDotAI/nbdev
Presence of `Raises` section on Numpy docstring causes obscure error when compiling docs
- Lingua principale
- Jupyter Notebook
- Stelle
- 5.3k
- Fork
- 513
- Merge medio
- 2g 30m
- PR unite (30g)
- 8
Descrizione
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!
Guida per i contributori
Apri la guida per i contributori
Direzione di ricerca
Inizia riproducendo il MWE durante la generazione della documentazione e confrontalo con il comportamento di show_doc usato manualmente. Ispeziona fastcore/docscrape.py attorno alla chiamata a dedent_lines segnalata e determina se la sezione Raises debba essere gestita in quel punto o segnalata più chiaramente. Il lavoro è completato quando il MWE non produce più un’eccezione oscura e il comportamento risultante è coperto da un test appropriato, se il repository ne fornisce uno.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Valutazione
- Stack tecnologico
- jupyter-notebook, python
- Ambito
- documentation
- Tipo di issue
- Bug
- Difficoltà
- 3/5
- Tempo stimato
- 1-2 giorni
- Stato di attività
- Ferma
- Chiarezza
- Abbastanza chiara
- Idoneità per principianti
- 35/100