Hacktoberfest 2026 : les issues que les mainteneurs ont marquées pour octobre, ouvertes et accessibles aux débutants. Parcourir les issues Hacktoberfest

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

Ouverte
  • Quelque chose ne va pas ?
#1,506 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub

Personne n'a encore pris cette issue.

Évaluation

Difficulté
3/5
Temps estimé
1-2 jours
Accessibilité débutants
35/100
Type d'issue
Bug
Clarté
Plutôt claire
Activité
À l'abandon
Stack technique
jupyter-notebook, python
Domaine
documentation

Piste de recherche

Commencez par reproduire le MWE lors de la génération de la documentation et comparez-le au comportement de show_doc utilisé manuellement. Inspectez fastcore/docscrape.py autour de l’appel à dedent_lines signalé et déterminez si la section Raises doit être traitée à cet endroit ou signalée plus clairement. Le travail est terminé lorsque le MWE ne produit plus d’exception obscure et que le comportement obtenu est couvert par un test approprié, si le dépôt en fournit un.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Description

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!

Langage dominant
Jupyter Notebook
Étoiles
5.3k
Forks
518
Merge moyen
1 j 3 h
PR mergées (30 j)
2

Préparer son environnement

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de AnswerDotAI/nbdev

Toutes les issues de AnswerDotAI/nbdev

Issues similaires

Plus d'issues Documentation

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.