numpyスタイルを使用して Python モジュールを文書化し、 sphinxとnumpydoc拡張機能を使用して HTML ドキュメントを生成しているときに、箇条書きに関するバグ (または機能?) に遭遇しました。
In reStructuredText (and sphinx/numpydoc), a single-lined paragraph
- with an immediately following
- bullet list
- is allowed,
but if you have a "long" paragraph,
which may be spanning several lines,
- a following bullet list
- results in an `ERROR: Unexpected indentation`.
With a blank line added between the "long" paragraph, which again
may span multiple lines, and the following list,
- bullet lists
- work fine again.
reStructuredText リファレンスによると、箇条書きリストには前後に空行が必要です。
したがって、私が知りたいのは、最初のバージョンが機能するのはなぜですか (機能しないのに)、2 番目のバージョン (機能しない) と何が大きく異なるのですか?
編集：
生成された html では、最初と最後のバージョンで外観が異なります。先頭の空行のない箇条書きリストの外観が必要な場合 (html のスペースが少ない場合)、クイックフィックスを使用できます。
to escape every line break by a backslash.\
This way there's effectively only a single long line,
- which allows bullet lists
- even after long paragraphs.
これにより解析エラーが回避されますが、それでも理由の質問には答えられません :-)