sphinxで雑にコード例と実行結果を表示したい場合

sphinxで雑にコード例と実行結果を表示したい場合がある。コード例はliteralincludeを使うと便利。一方実行結果をどうするのかというのが悩みどころ。

現状はMakefileで出力結果を生成してliteralincludeで埋め込んでいる。

こういう感じ

.. literalinclude:: ../../examples/code.py

result

.. literalinclude:: ../../examples/code.output

この時code.pyからcode.outputを生成しておく必要がある。

以下のようなMakefileを作っている

examples/Makefile

%.output : %.py
  python $< > $@

default: $(shell ls *.py | sed 's/\.py$$/.output/g')

clean:
  rm -f *.output

*.output を生成するルールを定義している。あとは、既存の *.py から生成するべき *.output ファイルの名前を列挙している(これがdefaultタスクの依存になっている)。

実際に利用する場合には、トップレベルのMakefileで実行結果を出力するタスクを呼んだ後にsphinxを呼ぶタスクを呼んでいる。

ディレクトリ階層は以下の様な感じ。

.
├── Makefile
├── docs
│   └── Makefile  # ここにsphinx用のファイルが色々
└── examples
    ├── Makefile
    ├── code.output
    └── code.py

トップレベルのMakefileから以下の順でmakeを呼ぶ

トップレベルのMakefileは以下のようなもの

docs: run
  $(MAKE) html -C docs
.PHONY: docs

run:
  $(MAKE) -C examples
.PHONY: run

ここなどで使っている。