Sphinxでデータを読み込みたい
shotakahasphinxcontrib.datatemplates
Sphinxはincludeを使って外部ファイルを読み込むことができるけど、ファイルの中身がそのままreST（やMyST）として表示されるだけ。
csv-tableやlist-tableで読み込んでも「テーブル」としてしか表示できない。
このsphinxcontrib.datatemplatesでは、.. datatemplate:データ形式::というディレクティブを新しく定義していて、そのbody部分でJinja2の構文を使ったテンプレートを使うことができる。
そのページだけでデータを読み込みたい、という場合にとても便利。
shotakaha普通にPythonパッケージを作っている場合、「そのページだけ外部データを読み込みたい」ということはおそらくないかもしれない。。。
shotakahaNo Data Sample
:::{datatemplate:nodata}
- {{ data }}
:::
とりあえずサンプルを試してみる。
外部データがない場合はdatatemplate:nodataを使うことができる。
読み込んだデータは{{ data }}を使って表示できる。
このサンプルではNoneとなっているので、次の内容のファイルとしてビルドされる。
- None
Sphinxが持っている変数を表示できる。
次のサンプルは、ドキュメントにあるファイル名とそのタイトルを表示できる。
:::{datatemplate:nodata}
Document titles from the Sphinx environment:
{% for doc, title in env.titles.items() %}
- ``{{ title }} ({{ doc }})``
{% endfor %}
:::
{% for ... %} / {% endfor %}の部分がJinja2構文で書かれたfor文。
env.titlesにドキュメント内のタイトル情報が入っている（のだと思う）。
だからdoc, titleでそれぞれタイトルとファイル名を取得できる。
このサンプルは次の内容のファイルとしてビルドされる。
Document titles from the Sphinx environment:
- タイトル (ファイル名)
- タイトル (ファイル名)
- タイトル (ファイル名)
CSVを読み込む
:::{datatemplate:csv} sample.csv
---
template: "csv-sample.tmpl"
headers:
dialect: "excel-tab"
---
CSVを読み込むサンプル。いきなりレベルあがった気がするのでドキュメントをちゃんと読む。
shotakahaオプション: template
レンダリング時に使うテンプレートはtemplateで指定されているファイルcsv-sample.tmpl。
このファイルがどこにあるかというと、conf.pyのtemplate_pathで設定したぱす。デフォルトだと_templates。
ここに、自分が作成したいページのテンプレートを作成し、datatemplateに読み込ませることができる。
shotakahaオプション: headers
これはboolean。
Trueにすると、データを読み込んだときdataが辞書型になるっぽい。デフォルトはFalseでリスト型。
このパッケージにヘルパー関数に、
make_list_tablemake_list_table_from_mapping
の2つがある。
それぞれ指定できるデータがリスト型と辞書型なので、たぶんここと組み合わせてON/OFFにできるようにもなっているのだと思う。
shotakahaオプション: dialect
ドキュメントには情報がないようなので、ソースコードを覗いてみた。
sphinxcontrib/datatemplates/loaders.pyでdialectで検索。
csv.reader or csv.DictReaderに渡しているオプションのよう。
dialect: "auto"にすることもできるみたい。
その場合、csv.Snifferを使っていい感じに形式を推定してくれるみたい。
ということで、Pythonにビルトインのcsvモジュールのドキュメント内を探してみると、Dialectクラスにある値（excel / excel-tab / unix）が指定できそう。