Sphinxをはじめよう 第3版

はじめに

1章　Sphinxとは
    1.1　Sphinxを何に使うのか
        1.1.1　Sphinxで技術ドキュメントを書く
        1.1.2　SphinxでWebサイトを作成する
        1.1.3　Sphinxで本を書く
        1.1.4　その他色々
        1.1.5　Sphinxが向かない分野
    1.2　Sphinxの用語と特徴
        1.2.1　Sphinxの用語
        1.2.2　Sphinxのよくある利用例
        1.2.3　docutilsとreSTの設計思想
        1.2.4　Sphinxの難しいところ
        1.2.5　Sphinxの嬉しいところ
    1.3　Sphinxと比較されるツール
        1.3.1　SphinxとOfficeスイートの違い
        1.3.2　SphinxとWikiの違い
        1.3.3　SphinxとMarkdown+Jekyllの違い
    1.4　まとめ

2章　Sphinxのインストール
    2.1　Windows環境へのインストール
    2.2　macOS環境へのインストール
        2.2.1　Command Line Tools for Xcodeのインストール
        2.2.2　Pythonのインストール
        2.2.3　Sphinxのインストール
    2.3　Linux環境へのインストール
    2.4　まとめ

3章　HTMLに変換してみよう
    3.1　Sphinxによるドキュメント作成の流れ
    3.2　プロジェクトの作成
        3.2.1　はじめてのビルド
    3.3　議事録を書こう
        3.3.1　会議名、議題 ―セクション
        3.3.2　参加者と日時 ―リスト
        3.3.3　会議の目的 ―段落、引用文
        3.3.4　状況の報告 ―リストとサブリスト
        3.3.5　決定事項 ―インライン記法
        3.3.6　外部資料 ―ハイパーリンク
        3.3.7　日程調整、まとめ ―コメント
        3.3.8　完成した議事録
    3.4　HTMLテーマを使おう
        3.4.1　ビルド設定ファイル（conf.py）の編集
        3.4.2　その他のHTMLテーマ
        3.4.3　HTMLテーマのカスタマイズ
    3.5　まとめ

4章　PDFに変換してみよう
    4.1　インストール手順書を書いてみよう
        4.1.1　TeXを使ったPDFへの変換
        4.1.2　いつだってquickstartから
        4.1.3　表を書いてみよう
        4.1.4　実行コマンドを書いてみる
        4.1.5　PDFに変換する
    4.2　いくつかのパートに分けて文章を書く
        4.2.1　原稿を複数のファイルに分割する
        4.2.2　toctreeと文書構造
        4.2.3　さらに大きい文書を書く場合
    4.3　まとめ

5章　EPUBに変換してみよう
    5.1　画像を埋め込む
    5.2　他のページを参照する
        5.2.1　ラベルを付ける
        5.2.2　参照を作る
    5.3　EPUBに変換する
    5.4　書籍の出力オプションを設定する
        5.4.1　表紙を設定する
        5.4.2　出版に使う情報を設定する
        5.4.3　ちょっとしたヒント
    5.5　まとめ

6章　画像の変換と埋め込み
    6.1　基本中の基本、figureディレクティブ
        6.1.1　figureディレクティブのオプション
        6.1.2　Sphinxで扱うことのできる画像形式
        6.1.3　出力形式に合わせて適切な画像ファイルを切替える
    6.2　Cacooを利用する
        6.2.1　Cacooクイックツアー
        6.2.2　Cacooで作成した図をSphinxから利用する
        6.2.3　自動化する
        6.2.4　Cacoo拡張のインストール・設定
        6.2.5　Cacoo拡張を使って図を埋め込む
        6.2.6　その他のツールへの対応
    6.3　まとめ

7章　おわりに

付録A　reStructuredTextリファレンス
    A.1　インライン記法
    A.2　インライン記法（ロール）
    A.3　段落
    A.4　コメント
    A.5　セクション名
    A.6　ページ内目次（contents）
    A.7　番号なしリスト
    A.8　番号付きリスト
    A.9　定義リスト
    A.10　画像（figure）
    A.11　図表番号による参照（numref）
    A.12　ハイパーリンク
    A.13　URL
    A.14 email
    A.15　外部ハイパーリンクターゲット
    A.16　名前付きハイパーリンク参照
    A.17　名前なしハイパーリンク
    A.18　埋め込みURL記法
    A.19　インライン内部ターゲット
    A.20　ラベル
    A.21　クロスリファレンス（ref）
    A.22　別原稿ファイルへのリンク（doc）
    A.23　ダウンロード用リンク（download）
    A.24　ラインブロック
    A.25　引用ブロック
    A.26　クォートリテラルブロック
    A.27　リテラルコードブロック（::）
    A.28　コードブロック（code-block）
    A.29　コードの引用（literalinclude）
    A.30　パースドリテラル（parsed-literal）
    A.31　テーブル（simple table）
    A.32　テーブル（grid table）
    A.33　CSVテーブル（csv-table）
    A.34　リストテーブル（list-table）
    A.35フィールドリスト
        A.35.1 docinfo
    A.36　TOCツリー（toctree）
    A.37　脚注
    A.38　引用参照
    A.39　注釈（note、warning）
    A.40　数式（math）
    A.41　RFC、PEP
    A.42　オプションリスト
    A.43　置換
        A.43.1　置換変数
    A.44　用語集（glossary）
    A.45　用語参照（term）
    A.46　インクルード（include）
    A.47　raw

付録B　Sphinxが使える出力形式
    B.1　本書で説明したビルダー
    B.2　HTML
    B.3　ヘルプブラウザ
    B.4　内部データ構造
    B.5　その他

付録C　TeX Live/MacTeXのインストール
    C.1　Windows環境へのTeX Live 2021のインストール
    C.2　macOS環境へのMacTeXのインストール
    C.3　Linux環境へのTeX Live 2021のインストール

付録D Markdownで書いてみよう
    D.1　Markdownの歴史
        D.1.1　CommonMark
    D.2　SphinxでMarkdown原稿を扱う
        D.2.1　MyST-Parserのインストール
    D.3　Markdown原稿を書いてみよう
        D.3.1　記法の違い
付録E Sphinxのコミュニティ（sphinx-users.jp）
    E.1　情報交換の場の提供
    E.2　イベントの開催
    E.3　Sphinxに関する日本語情報の発信

謝辞
索引

コラム目次
    SphinxとPythonのバージョンの関係
    Sphinxと差分更新
    テキストエディタの設定
    セクション名の装飾の長さ
    改行位置を維持する
    reSTとスペース
    サブリストと空行
    サブリストとベースラインの関係
    番号付きリストのベースライン
    エスケープ文字
    conf.pyはPythonスクリプト
    ディレクティブとは
    ディレクティブとインデント
    さまざまな表の書き方
    ソースコードをハイライト表示する
    最初の見出しのゆくえ？
    セクションのないファイル？
    定義リストの書き方
    ファイルを分割するポイント
    ラベル名に利用できる文字は？
    図表番号でリンク
    ルビへの対応
    画像形式を自動変換する
    Sphinx拡張とは
    複数のSphinx拡張を同時に利用する
    エクスポート機能との使い分け
    古いTeXにはご用心！？