메뉴
Sphinx ドキュメント・スライドを Makefile 経由でビルドするスキル(HTML・latexpdfja・EPUB・linkcheck・livehtml・revealjs)。ドキュメントやスライドのビルド・プレビュー・開発サーバー起動・リンクチェックを求められたときに使用する。パッケージマネージャ検出とビルドエラーの解釈は本文参照。
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
| name | sphinx-build |
| description | Sphinx ドキュメント・スライドを Makefile 経由でビルドするスキル(HTML・latexpdfja・EPUB・linkcheck・livehtml・revealjs)。ドキュメントやスライドのビルド・プレビュー・開発サーバー起動・リンクチェックを求められたときに使用する。パッケージマネージャ検出とビルドエラーの解釈は本文参照。 |
| license | MIT |
| allowed-tools | Bash, Read |
検出優先順位 (該当した時点で確定):
| 優先 | 判定条件 | 採用 |
|---|---|---|
| 1 | uv.lock が存在 | uv |
| 2 | poetry.lock が存在 | poetry |
| 3 | Pipfile.lock が存在 | pipenv |
| 4 | .venv/ のみ存在 (lockfile なし) | plain venv |
| 5 | 上記すべて該当しない | ユーザー問い合わせ (推奨: uv) |
ビルド (make) 実行コマンド:
uv run make -C docs <target>poetry run make -C docs <target>pipenv run make -C docs <target>source .venv/bin/activate && make -C docs <target>検出した PM のコマンドが PATH に無ければ例外送出 (フォールバック禁止)。
docs/Makefile 存在 — 不在なら明示的エラー伝播 + sphinx-init 誘導 (Makefile 自動生成等の暗黙処理は行わない)pyproject.toml のあるディレクトリ) 前提。サブディレクトリから呼ばれた場合はプロジェクトルートへ移動してから実行docs/Makefile に revealjs ターゲットが存在し、かつ docs/conf.py の extensions に sphinx_revealjs を含む場合、スライドプロジェクトとみなす:
revealjs にマッピングするlivehtml は Makefile 側で -b revealjs 動作となる (revealjs-init が生成)| ユーザー意図 | 実行コマンド (uv 例、PM ごとに動的書き換え) |
|---|---|
| HTML ビルド | uv run make -C docs html |
| クリーンビルド | uv run make -C docs clean html |
| PDF (英文) | uv run make -C docs latexpdf |
| PDF (日本語) | uv run make -C docs latexpdfja |
| EPUB | uv run make -C docs epub |
| ライブリロード | uv run make -C docs livehtml |
| ポート指定ライブリロード | PORT=8003 uv run make -C docs livehtml |
| リンクチェック | uv run make -C docs linkcheck |
| スライドビルド (Reveal.js) | uv run make -C docs revealjs |
| ヘルプ | uv run make -C docs help |
PM ごとの実コマンド書き換えは冒頭の「パッケージマネージャ検出」セクションを参照。
ビルド失敗時、出力を解析して以下のパターンに該当する場合は修正候補を提示:
WARNING: undefined label → 参照先ラベルの定義箇所を提示、修正候補WARNING: document isn't included in any toctree → toctree 追加提案Could not import extension → uv add <pkg> --group docs 提案Could not import extension sphinx_revealjs → uv add sphinx-revealjs --group docs 提案。プロジェクトが未初期化なら revealjs-init 誘導latexpdfja 失敗) → upLaTeX / dvipdfmx インストール手順 (TeX Live 等)PORT=8003 等の代替ポート提案sphinx-init (Makefile が無ければ誘導)、revealjs-init (スライドプロジェクトの初期化)sphinx-config (拡張不在エラー時の依存追加)Sphinx ドキュメントの MyST Markdown 執筆支援スキル(ディレクティブ・ロール・相互参照・数式・sphinx-design)。extensions に myst_parser があるプロジェクトで docs/ 配下の .md を編集・作成するときや、MyST 記法について質問されたときに使用する。
sphinx-revealjs のスライドを MyST で書くための記法ルール(見出しレベルによるスライド分割、list-table、2 カラムレイアウト等)。extensions に sphinx_revealjs があるプロジェクトで docs/ 配下の .md を編集・作成するときに使用する。汎用 MyST 記法は myst-authoring が担当。
sphinx-revealjs の conf.py 設定(プラグイン・コードハイライト・テーマ・スライド寸法・表の中央寄せ・Mermaid 統合)の知識を提供するスキル。sphinx-revealjs プロジェクトでスライドの見た目や挙動を変更・修正するときに使用する。conf.py 編集の実行は sphinx-config に委譲する。
sphinx-revealjs によるスライド専用プロジェクトを初期化するスキル。docs/ が未作成のプロジェクトで発表スライドの新規作成を求められたときに使用する。依存追加・MyST テンプレート生成・テーマ選定・Makefile 整備までを行う。
既存の reStructuredText 製 Sphinx ドキュメントを rst-to-myst で MyST Markdown へ移行するスキル。実質的な RST コンテンツを持つプロジェクトの移行を求められたときに使用する(sphinx-quickstart の雛形だけの場合は対象外)。変換結果を検証してから元ファイルを削除する。
docs/conf.py を既存設定を保ちながら安全に更新するスキル。Sphinx 拡張の追加・削除、テーマ、プロジェクトメタデータなど conf.py の変更を求められたときに使用する。