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
docs: run $(MAKE) html -C docs .PHONY: docs run: $(MAKE) -C examples .PHONY: run
例
ここなどで使っている。