Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

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

Abierto
  • ¿Algo no está bien?
#1,506 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
3/5
Tiempo estimado
1-2 días
Aptitud para principiantes
35/100
Tipo de issue
Error
Claridad
Bastante claro
Estado de actividad
Estancado
Stack tecnológico
jupyter-notebook, python
Área
documentation

Línea de trabajo

Comienza reproduciendo el MWE durante la generación de documentación y compáralo con el comportamiento de show_doc usado manualmente. Inspecciona fastcore/docscrape.py alrededor de la llamada a dedent_lines indicada y determina si la sección Raises debe gestionarse ahí o notificarse de forma más clara. Se considera completado cuando el MWE ya no produce una excepción obscura y el comportamiento resultante está cubierto por una prueba adecuada, si el repositorio proporciona una.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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!

Lenguaje dominante
Jupyter Notebook
Estrellas
5.3k
Forks
517
Merge medio
1 min
PR fusionados (30 d)
3

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de AnswerDotAI/nbdev

Todos los issues de AnswerDotAI/nbdev

Issues similares

Más issues de Documentation

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.