あめだまふぁくとりー

Boost.Graphとかできますん

sphinx-docxbuilderを復活させた

f:id:amedama41:20190407155426p:plain

どうしても Office Word を使いたくなかったので, sphinx-docxbuilder を復活させまし た. ソースは GitHub にあげています.

最初はちょっと手を入れる程度だったのですが, テーブル周りに色々問題があったりで修正しすぎてソースコードの原型はほとんどなくなりました.

インストール

pip でインストールできます

pip install docxbuilder

使い方

conf.pyextensions 設定に "docxbuilder" を追加して, make docx を実行するだけです.

設定

ドキュメントのファイル名等は docx_documents 設定で行います.

# index.rst をドキュメントのルートとし, index.rst の TOC ツリー以外は除外する
# 出力ファイル名は docxbuilder.docx で title, creator, subject プロパティを設定する.
docx_documents = [
  ('index', 'docxbuilder.docx', { 'title': 'Title', 'creator': 'Author', 'subject': 'A manual of docxbuilder', }, True),
]

設定値はタプルのリストになっており, タプルの最初の値はルートとなるドキュメントファイル (通常は index), 二つ目は出力ファイル名, 三つ目はドキュメントのプロパティ, 四つ目はルートドキュメントファイルの TOC ツリー以外の要素を除外するかどうかを示します.

デフォルトスタイルファイルの表紙は title, creator, subject プロパティを参照しているので, この三つのプロパティは指定しておくとよいです.


スタイルファイルは docx_style 設定で指定できます.

docx_style = 'path/to/custom_style.docx' # カスタムスタイルファイルを指定する.

Word のスタイルはパラグラフを分割させないような指定もできるのですが, スタイルファイルで指定するのは面倒なので, パラグラフや図表の配置は docxbuilder の中でできるだけいい感じになるように頑張っています. 表については docx_table_options 設定や特定のクラスを指定することで, 表が複数のページに分割されないようにしたり, 表を横長のページに配置することも可能です.


docx_coverpage 設定で表紙を追加するかどうか指定します.

docx_coverpage = True # 表紙を挿入

表紙は自動生成するのではなく, スタイルファイルの表紙が挿入されます. また, 表紙の定義は "Cover Pages" タグが指定されたページなのですが, このタグを明示的に指定する方法は多分ないので, 自前の表紙を作る際は Word の表紙挿入機能でプリデザインの表紙を挿入して, それを編集する必要があります.


docx_pagebreak_before_section 設定で,セクションタイトルの前で改ページすることが可能です.

docx_pagebreak_before_section = 2  # セクションレベルが 2 以下 (章と節) のタイトルはページの先頭に配置

指定した数値以下のセクションレベルを持つタイトルはページの先頭に配置されるように改ページされます. 最小のレベルは 1 です. デフォルトの設定値は 0 なので一切改ページされません.


目次は最初のセクションの前にある場合もあり, 目次の後に改ページしたいかもしれません. その場合は, docx_pagebreak_after_table_of_contents 設定を使用します.

docx_pagebreak_after_table_of_contents = 0 # セクションレベル 0 以下のセクションに登場する目次の後で改ページ

表の配置については docx_table_options 設定を使用します.

docx_table_options = {
  'landscape_columns': 6,      # 列数が 6 以上の表は横長のページに配置
  'in_single_page': True,      # 可能な限り表が複数のページに分割されないようにする
  'row_splittable': True,      # セルが複数ページに跨ってもよい
  'header_in_all_page': True,  # 表が複数ページに分割される場合, すべてのページに表のヘッダーを表示する
}

この設定はすべての表に適用されます. 個別に設定したい場合は表にクラスを指定します (後述).

ドキュメントのカスタマイズ

ドキュメントのスタイル

ドキュメントの見た目はスタイルファイルを使って変更可能です. スタイルファイルは Word のファイルで, ドキュメントに適用するスタイルや目次, ページ設定 (余白やヘッダ等) を定義します.

docxbuilder で使用するスタイルには文字スタイル, パラグラフスタイル, 表スタイルの三種類のスタイルがあります.

主に使用するスタイルは こちら を参照してください. docxbuilder はスタイル名 (Emphasis, Body Text 等) とスタイル種別 (文字, パラグラフ, 表) をチェックしてスタイルを適用するので, この二つの定義は間違えないようにしてください.

また, List Bullet と List Style は箇条書きに適用されるスタイルで, このスタイルにはアウトラインの定義が必須です.

クラスによるカスタマイズ

図表が横長になる場合, 横長のページにそれらを配置したくなるケースがあります. その場合, docx-landscape クラスを指定するとよいです.

.. rst-class: docx-landscape
.. list-table::

   * - cell1-1
     - cell1-2
   * - cell2-1
     - cell2-1

図に使用できるクラスは docx-landscape クラスだけですが, 表には他にも docx-in-single-page, docx-row-splittable, docx-header-in-all-page が使用可能です (効果は docx_table_options のものと同じです).

今後の予定

現状数式は latex の数式そのままが出力されるので, Word の数式として出力したいです (これ を使って latex 数式を MathML に変換して, MathML を OMML に変換する予定).