ビルダー

typsphinxは、異なる用途に対応する2つのビルダーを提供しています。

概要

ビルダー

出力

使用ケース

typst

.typ ファイル

Typstマークアップを手動で編集、外部のTypst CLIを使用

typstpdf

.pdf ファイル

直接PDF生成、CI/CDパイプライン

typst ビルダー

typst ビルダーは、Typstマークアップファイル（.typ）を生成します。

使用方法

sphinx-build -b typst source/ build/typst

出力

  • 出力ディレクトリに .typ ファイルを生成します

  • typst_documents で定義された各ドキュメントにつき1ファイルを生成します

  • 複数ドキュメントプロジェクト用のインクルードファイルを含みます

使用すべき場合

  • 生成されたTypstマークアップを編集したい場合

  • 特定のTypst CLIバージョンを使用する場合

  • コンパイルを細かく制御する必要がある場合

  • Typst構文を学びたい場合

手動コンパイル

.typ ファイルを生成した後、Typst CLIでコンパイルします：

# Install Typst CLI if needed
# https://github.com/typst/typst

# Compile to PDF
typst compile build/typst/index.typ output.pdf

typstpdf ビルダー

typstpdf ビルダーは、typst-pyを使用してPDFファイルを直接生成します。

使用方法

sphinx-build -b typstpdf source/ build/pdf

出力

  • .pdf ファイルを直接生成します

  • 外部ツールは不要です

  • typst-py Pythonバインディングを使用します

使用すべき場合

  • すぐにPDF出力が必要な場合

  • Typst CLIなしでCI/CDを実行している場合

  • 自己完結型のビルドが必要な場合

  • Typstマークアップを編集する必要がない場合

利点

  • 外部依存関係なし: すべてPython内で実行されます

  • 高速なセットアップ: Typst CLIをインストールする必要がありません

  • 再現可能なビルド: 環境間で同じ出力を得られます

  • CI/CDに適合: 制限された環境でも動作します

設定

両方のビルダーは、conf.py で同じ設定オプションを共有します。

ドキュメント定義

typst_documents = [
    # (source, output, title, author, class)
    ("index", "main", "My Document", "Author", "typst"),
    ("api", "api-ref", "API Reference", "Author", "typst"),
]

ビルダー固有のオプション

現在、ビルダー固有のオプションはありません。すべての typst_* 設定オプションは両方のビルダーに適用されます。

ビルダーの選択

typst を使用すべき場合：

  • 生成されたTypstコードをカスタマイズしたい場合

  • 特定のTypst CLI機能が必要な場合

  • Typstを学習中でマークアップを確認したい場合

typstpdf を使用すべき場合：

  • 単にPDF出力が必要な場合

  • CI/CDでビルドしている場合

  • 最もシンプルなワークフローが必要な場合

  • Typstコードを編集する必要がない場合

一般的なワークフロー

開発

開発中は、迅速なフィードバックのために typstpdf を使用します：

sphinx-build -b typstpdf source/ build/pdf
open build/pdf/index.pdf

プロダクション

プロダクション環境では、どちらのビルダーも使用できます：

# Option 1: Direct PDF (recommended)
sphinx-build -b typstpdf source/ build/pdf

# Option 2: Typst + manual compilation
sphinx-build -b typst source/ build/typst
typst compile build/typst/index.typ output.pdf

CI/CD

CI/CDでは、シンプルさのために typstpdf が推奨されます：

- name: Build Documentation PDF
  run: |
    pip install typsphinx
    sphinx-build -b typstpdf docs/source docs/build/pdf

関連項目