sphinxcontrib.datatemplates

Sphinxはincludeを使って外部ファイルを読み込むことができるけど、ファイルの中身がそのままreST（やMyST）として表示されるだけ。
csv-tableやlist-tableで読み込んでも「テーブル」としてしか表示できない。

このsphinxcontrib.datatemplatesでは、.. datatemplate:データ形式::というディレクティブを新しく定義していて、そのbody部分でJinja2の構文を使ったテンプレートを使うことができる。
そのページだけでデータを読み込みたい、という場合にとても便利。

shotakaha

普通にPythonパッケージを作っている場合、「そのページだけ外部データを読み込みたい」ということはおそらくないかもしれない。。。

shotakaha

No Data Sample

MyST形式

:::{datatemplate:nodata}
- {{ data }}
:::

とりあえずサンプルを試してみる。
外部データがない場合はdatatemplate:nodataを使うことができる。
読み込んだデータは{{ data }}を使って表示できる。
このサンプルではNoneとなっているので、次の内容のファイルとしてビルドされる。

処理される内容

- None

Sphinxが持っている変数を表示できる。
次のサンプルは、ドキュメントにあるファイル名とそのタイトルを表示できる。

MyST形式

:::{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:
- タイトル (ファイル名)
- タイトル (ファイル名)
- タイトル (ファイル名)

shotakaha

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_table
make_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）が指定できそう。