sphinxcontrib-xlsxtable

SphinxでExcelファイルから表 (テーブル) を埋め込むSphinx拡張を作りました。

• PyPI sphinxcontrib-xlsxtable
• GitHub sphinxcontrib-xlsxtable

機能的に不十分だったり、Pythonモジュールよくわかってなかったり、PyPIの理解も不十分だったりしますが、まあ、動いとる。

以下が特徴で、これはそのまま自分が必要とした機能であり、既存の拡張機能が肌に合わなかった理由になります。

• Excelファイルの制御はOpenPyXLを使用しており、xlsxファイルのサポート範囲が広い
• Sphinx標準表記の表 (テーブル) として出力される
• 結合セル対応

使い方

pipで入れて、

$ pip install sphinxcontrib-xlsxtable

conf.pyに設定します。

# conf.py
extensions = [
    'sphinxcontrib.xlsxtable',
]

reStructuredTextのディレクティブは次の通りです。現状はほとんどオプションはありませんが、いくらか追加予定です。

ドキュメント化していませんが、一応シート指定にも対応してます。

.. xlsx-table:: Table Caption
   :file: path/to/xlsx/file.xlsx
   :header-rows: 1
   :sheet: Sheet

これによって、以下のExcelファイルから、

Excel

以下の結果が得られます。

結果

セル内の文字列はそのままreSTとして処理されるので、上記の通り「- テキスト」形式で書かれた部分は、箇条書きとして処理されています。

内部でGrid Table文字列を生成

仕組みとしては、OpenPyXLでExcelファイルを解析して、内部でreSTのGrid Tableの文字列を作っています。

上記のExcelファイルだと、以下のような感じ。

+----+-------+-----------+--------+
| A1 | B1    | C1        | D1     |
+====+=======+===========+========+
| A2 | B2:B3 | C2        | D2     |
+----+       +-----------+--------+
| A3 |       | 日本語              |
+----+-------+-----------+--------+
| A4 | B4    | C4        | - D4-1 |
|    |       |           | - D4-2 |
+----+-------+-----------+--------+

作った文字列はそのままdocutils標準の解析器 / 生成器に渡しているだけ (のつもり) なので、結合セル、セル内のreST表記に対応し、標準の表のスタイルで表示することを実現しています。

Sphinx / reStructuredTextの表について

元々はSphinxで結合セルの表記をするならExcelから読み込みたい...というので作ったのだけど、使ってみたところ思いの外便利でした。

• 大規模な表はCSV Table使おうと思ってたけど、CSVの編集が思ったより大変
  • Excelで開いても表示のレイアウトが維持されないので、割と辛い
• 既存のExcelファイルをそのまま使えるのが強い
  • 既存ドキュメントのまとめ直しで、既存ファイルをそのまま使える
• Excelで表作るのやっぱ楽。