Presence of `Raises` section on Numpy docstring causes obscure error when compiling docs
まだ誰も着手していません。
評価
- 難易度
- 3/5
- 見積もり時間
- 1〜2日
- 初心者へのやさしさ
- 35/100
- issue の種類
- バグ
- 明瞭さ
- おおむね明確
- 活発さ
- 停滞
- 技術スタック
- jupyter-notebook, python
調査の方向性
まず、ドキュメント生成中に MWE を再現し、手動での show_doc の動作と比較します。報告された dedent_lines 呼び出しの周辺にある fastcore/docscrape.py を調べ、Raises セクションをそこで処理すべきか、より明確に報告すべきかを判断します。MWE が不明瞭な例外を生成しなくなり、その結果の動作が、リポジトリに適切なテストが用意されている場合はそのテストでカバーされれば完了です。
索引モデルが issue の本文から書いたものです。
説明
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!
- 主要言語
- Jupyter Notebook
- スター
- 5.3k
- フォーク
- 517
- 平均マージ
- 1分
- マージ済み PR（30日）
- 3
環境構築
- Dockerfile・Docker Compose ファイルなし
- プルリクエストのテンプレートなし
- コントリビューションガイドを読む
はじめの一歩
- issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
- 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
- リポジトリをフォークし、ブランチを切って変更します。
- issue 番号を参照したプルリクエストを送ります。
AnswerDotAI/nbdev のほかの issue
-
Bug Report: `nbdev` Parser `IndexError` on `@patch_to` with Keyword Arguments対応中かも @ruchi-mish90 が 86 日前に担当しました。 オープンbug
難易度 2/5 1〜3時間 初心者へのやさしさ 78/100
AnswerDotAI/nbdev#1596 · コメント 1 件 ·
-
難易度 5/5 1週間以上 初心者へのやさしさ 25/100
AnswerDotAI/nbdev#1587 ·
-
Interested in Windows support?対応中かも @mrexodia が 10 日前に担当しました。 オープン
難易度 4/5 3〜5日 初心者へのやさしさ 35/100
AnswerDotAI/nbdev#1584 · コメント 1 件 ·
-
難易度 3/5 1〜2日 初心者へのやさしさ 35/100
AnswerDotAI/nbdev#1583 · コメント 1 件 · リアクション 1 件 ·
-
bug
難易度 3/5 1〜2日 初心者へのやさしさ 52/100
AnswerDotAI/nbdev#1581 ·
AnswerDotAI/nbdev の issue をすべて見る
似ている issue
-
難易度 1/5 1時間未満 初心者へのやさしさ 85/100
-
Table: Space fires onActivate in single-selection mode — the reference doc and the JSDoc disagreeオープン
難易度 2/5 1〜3時間 初心者へのやさしさ 68/100
sidorares/react-x11-components#764 ·
メンテナーはふだん 1 日以内に返信
-
難易度 1/5 1時間未満 初心者へのやさしさ 71/100
t4t5/omdrop-owl#14 ·
メンテナーはふだん 1 日以内に返信
-
documentation
難易度 1/5 1時間未満 初心者へのやさしさ 91/100
githubnext/gh-aw-workshop#4458 ·
メンテナーはふだん 1 日以内に返信
-
bug:new
難易度 1/5 1時間未満 初心者へのやさしさ 84/100
callstackincubator/simlock#451 ·
メンテナーはふだん 1 日以内に返信