메뉴
docs/conf.py を既存設定を保ちながら安全に更新するスキル。Sphinx 拡張の追加・削除、テーマ、プロジェクトメタデータなど conf.py の変更を求められたときに使用する。
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
| name | sphinx-config |
| description | docs/conf.py を既存設定を保ちながら安全に更新するスキル。Sphinx 拡張の追加・削除、テーマ、プロジェクトメタデータなど conf.py の変更を求められたときに使用する。 |
| license | MIT |
| allowed-tools | Read, Edit, Bash |
検出優先順位 (該当した時点で確定):
| 優先 | 判定条件 | 採用 |
|---|---|---|
| 1 | uv.lock が存在 | uv |
| 2 | poetry.lock が存在 | poetry |
| 3 | Pipfile.lock が存在 | pipenv |
| 4 | .venv/ のみ存在 (lockfile なし) | plain venv |
| 5 | 上記すべて該当しない | ユーザー問い合わせ (推奨: uv) |
実行コマンド対応表:
| 操作 | uv | poetry | pipenv | plain venv |
|---|---|---|---|---|
| 依存追加 (docs グループ) | uv add <pkg> --group docs | poetry add --group docs <pkg> | pipenv install --dev <pkg> | pyproject.toml 手動編集 + pip install -e ".[docs]" |
| サブコマンド実行 | uv run <cmd> | poetry run <cmd> | pipenv run <cmd> | venv 有効化後 <cmd> |
| ビルド | 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 に無ければ例外送出 + インストール手順提示。デフォルト値による継続処理は禁止。
| カテゴリ | 拡張名 | 用途 | 追加パッケージ |
|---|---|---|---|
| 数式 | amsmath | LaTeX amsmath 環境 | — |
| 数式 | dollarmath | $..$ / $$..$$ 数式 | — |
| 属性 | attrs_inline | インライン属性 | — |
| 属性 | attrs_block | ブロック属性 | — |
| リスト | deflist | 定義リスト | — |
| リスト | tasklist | チェックボックスリスト | — |
| リスト | fieldlist | reST フィールドリスト | — |
| ブロック | colon_fence | ::: ディレクティブ | — |
| ブロック | html_admonition | <div class="admonition"> | — |
| ブロック | html_image | <img> タグ | — |
| テキスト | replacements | 記号自動変換 (©等) | — |
| テキスト | smartquotes | 引用符変換 | — |
| テキスト | strikethrough | ~~..~~ 取り消し線 | — |
| テキスト | substitution | Jinja2 置換 | — |
| リンク | linkify | bare URL 自動リンク化 | linkify-it-py |
sphinx-autobuild (3rd-party、Makefile livehtml 依存)| 拡張 | 種別 | 用途 |
|---|---|---|
sphinx-copybutton | 3rd-party | コードブロックコピーボタン |
sphinx-design | 3rd-party | カード / タブ / グリッド |
sphinx.ext.intersphinx | built-in | クロスリファレンス |
sphinx.ext.napoleon | built-in | Google/NumPy docstring |
| 拡張 | 種別 | 用途 | 連携外部スキル |
|---|---|---|---|
sphinx_oceanid | 3rd-party | Mermaid 図 | gh skill install drillan/sphinx-oceanid mermaid-diagram |
sphinx.ext.autodoc | built-in | docstring 自動抽出 | — |
sphinx.ext.viewcode | built-in | ソースコードリンク | — |
sphinx.ext.todo | built-in | TODO ディレクティブ | — |
myst-nb | 3rd-party | Jupyter Notebook 統合 | — |
編集対象セクションのみ変更。コメント、sys.path 操作、その他のユーザー設定はそのまま保持する。
3rd-party 拡張を extensions に追加する際は、検出した PM で対応コマンドを実行 (上記 PM 検出セクション参照)。
myst_enable_extensions リストの追加/削除を行う。linkify 追加時は対応 PM で linkify-it-py を docs 依存に追加。
編集失敗時の挙動を厳格に規定:
conf.py.bak を作成conf.py.bak から原本を復元したうえで、元のエラーを必ずユーザーへ例外送出 (復元成功で「正常終了」扱いにしない)conf.py.bak のパスと手動復元手順 (例: cp conf.py.bak conf.py) を提示して即時例外送出conf.py.bak を削除これにより「復元したから OK」というサイレントフェイル実装を仕様レベルで防止する。
sphinx-theme (テーマ変更時に html_theme と html_theme_options の更新で連携)sphinx-init (init 時の conf.py 反映)、rst-to-myst (変換後 myst-parser 追加)、revealjs-init (スライド init 時の conf.py 反映)、revealjs-config (revealjs_* 設定の反映)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 の雛形だけの場合は対象外)。変換結果を検証してから元ファイルを削除する。
Sphinx ドキュメント・スライドを Makefile 経由でビルドするスキル(HTML・latexpdfja・EPUB・linkcheck・livehtml・revealjs)。ドキュメントやスライドのビルド・プレビュー・開発サーバー起動・リンクチェックを求められたときに使用する。パッケージマネージャ検出とビルドエラーの解釈は本文参照。