エラーハンドリング

拡張を書いているときに、エラーを出したいときがあります。こういう時には、sphinx.errorsで定義されている例外を使いますと、通常の例外よりも表示が親切になります。

sphinx.errorsには以下の例外が定義されています。

  • SphinxError
  • SphinxWarning
  • ExtensionError
  • ConfigError
  • ThemeError
  • VersionRequirementError
  • PycodeError

使い方としては通常の例外と同じです。

from sphinx.errors import ExtensionError

raise ExtensionError("Could not load extension")

なお、SphinxWarningは「Errorとして扱うようなWarningについて用いる」との説明がついています。そのため、warningであってもその場でbuildがストップします。

警告のみとしたい

sphinx.application.warn()を使うことで、build時に警告表示が出来ます。Exceptionとは異なり、buildが停止することはありません。停止させたい場合はExceptionを使ってください。

なお、sphinx.applicationはappとして拡張を書くときにいろいろな場所で使われいます。

def SomeBuilder(Builder):

    def init(self):
        self.app.warn("------ Print Warning")
        self.app.info("------ Print Info")

こう書いておくと、

Running Sphinx v1.2
loading pickled environment... done
WARNING: ------ Print Warning
------ Print Info
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
preparing documents... done
writing output... [100%] index

build succeeded, 1 warning.

というように、画面上と最後に表示されます。

なお、上記例でも使っていますが、warnの他に

  • info

があり、こちらは最後のwarningの数には含まれません。また、Sphinx-1.2から

  • verbose
  • debug

-vオプションが追加されました。