Ablog のバグ¶
Ablog を色々試している間に、バグっぽいものを発見したのでメモしておく。 バージョンは 0.11.11 である。
条件と現象¶
Ablog の conf.py で、投稿一覧に抜粋(excerpt)を1行以上表示されるように設定し、 言語を ja に設定した状態で、 投稿用 ReST ファイルの先頭部分に contents ディレクティブを書くと、 投稿一覧の抜粋(excerpt)部分の1行目に以下のようなエラーが出る。
No directive entry for "contents" in module "docutils.parsers.rst.languages.ja". Using English fallback for directive "contents".
原因¶
エラーが出る流れを正確には追っていないのだが、エラーメッセージから推測するに、 およそ次のような感じであろう。
Sphinx は ReST ファイルの解析に docutils の ReST パーサを使用しているようだが、 このパーサは多言語化されており、Sphinx の言語設定を ja にしてある場合、 実はディレクティブを日本語で書いても正しく解析できる。つまり
.. 目次::
は
.. contents::
と同等に機能する。 (ReST のディレクティブを日本語で書いても処理が通るということを初めて知った。 まぁ面倒なのでそんなことはしないが)
逆に言うと、Sphinx の言語設定を ja にしてあると、パーサはディレクティブをまず 日本語として解析しようとする。英語表記のディレクティブは日本語の ディレクティブリストには入っていないので、fallback として英語の ディレクティブリストを探しに行く。 上記のエラーは、そのような fallback をしたよ、という程度のメッセージである。 エラーと言うよりはデバッグメッセージだな。
Sphinx 自体はこのメッセージを無視するので、Sphinx だけを使っている限り 気付かないのだが、Ablog はこのメッセージを律儀に拾ってしまうので、 表に出てきてしまう、ということらしい。
対策¶
ディレクティブを日本語で書く、あるいはパーサのディレクティブリストに 英語表記のエントリも追加してしまう、といった対策が考えられる。
わたしは、抜粋(excerpt)を表示しないことにしたので、 そもそも対策の必要が無くなった。
余談¶
docutils/parsers/rst/languages/ja.py に書かれている和訳は非日本人が 行ったらしく、苦労の後が見える。
# Corrections to these translations are welcome!
# 間違いがあれば、どうぞ正しい翻訳を教えて下さい。
という一文に同情を誘われる。