AnswerDotAI / AnswerDotAI/nbdev

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

Aperta
#1,506 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub
bug
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

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.