Hacktoberfest 2026: die Issues, die Maintainer für den Oktober markiert haben – offen und einsteigerfreundlich. Hacktoberfest-Issues durchsuchen

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

Offen
  • Stimmt etwas nicht?
#1,506 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Dieses Issue hat noch niemand übernommen.

Bewertung

Schwierigkeit
3/5
Geschätzter Aufwand
1-2 Tage
Anfängerfreundlichkeit
35/100
Issue-Typ
Bug
Klarheit
Größtenteils klar
Aktivitätsstatus
Veraltet
Tech-Stack
jupyter-notebook, python
Bereich
documentation

Rechercherichtung

Beginne damit, das MWE während der Dokumentationsgenerierung zu reproduzieren und mit dem Verhalten bei manueller Verwendung von show_doc zu vergleichen. Untersuche fastcore/docscrape.py rund um den gemeldeten Aufruf von dedent_lines und ermittle, ob der Abschnitt Raises dort behandelt oder klarer gemeldet werden sollte. Als erledigt gilt die Aufgabe, wenn das MWE keine undurchsichtige Ausnahme mehr erzeugt und das resultierende Verhalten durch einen geeigneten Test abgedeckt ist, falls das Repository einen solchen bereitstellt.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Beschreibung

bug

If a docstring is in Numpy format and contains a Raises section, which is part of the standard, the 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!

Vorherrschende Sprache
Jupyter Notebook
Sterne
5.3k
Forks
516
Ø Merge
2 T. 7 Std.
Gemergte PRs (30 T.)
1

Entwicklungsumgebung

Erste Schritte

  1. Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
  3. Forken Sie das Repository und arbeiten Sie in einem Branch.
  4. Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.

Mehr aus AnswerDotAI/nbdev

Alle Issues in AnswerDotAI/nbdev

Ähnliche Issues

Weitere Issues zu Documentation

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.