From pharaoh
Generates index.rst with Sphinx toctree for directory of emitted RST files, preventing orphan warnings under sphinx-build -W. Use after composition skills emit RST sets into Sphinx docs directories.
How this skill is triggered — by the user, by Claude, or both
Slash command
/pharaoh:pharaoh-toctree-emitThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Invoke at the end of a plan (emitted by `pharaoh-write-plan`, executed by `pharaoh-execute-plan`) that writes N RST files into a directory (e.g. `docs/source/features/`). Without an `index.rst` with a matching toctree, Sphinx treats every generated file as orphan and `sphinx-build -W` fails. This skill writes that index, and only that index.
Invoke at the end of a plan (emitted by pharaoh-write-plan, executed by pharaoh-execute-plan) that writes N RST files into a directory (e.g. docs/source/features/). Without an index.rst with a matching toctree, Sphinx treats every generated file as orphan and sphinx-build -W fails. This skill writes that index, and only that index.
Do NOT use to wire the emitted directory into its parent (e.g. updating the project-root index.rst to reference features/index). That is a separate caller concern — changes to the parent toctree are outside this skill's scope.
Do NOT use to patch an existing index.rst with different content — if an existing index disagrees with what this skill would write, the skill warns and does not overwrite. Caller decides whether to delete the existing file or merge manually.
index.rst file written (or no-op if already matches). No modifications to other RST files. No parent-toctree edits.{target_dir: str, file_glob: str, parent_caption: str, maxdepth?: int, exclude?: list[str]}. Output: JSON {toctree_path: str, files_included: list[str], files_modified: bool}.pharaoh-validation/fixtures/pharaoh-toctree-emit/input_dir/ containing three files (csv_export.rst, jama_pull.rst, reqif_import.rst). With target_dir = that path, file_glob = "*.rst", parent_caption = "Features", maxdepth = 1 → skill writes <target_dir>/index.rst whose content exactly matches the expected_index.rst fixture (same alphabetical ordering of stems, same caption, same maxdepth, same blank lines).pharaoh-write-plan may include N toctree-emit tasks (one per target_dir) dispatched by pharaoh-execute-plan, but this skill itself handles exactly one.target_dir: absolute path to the directory whose RST files should be indexed.file_glob: glob pattern applied within target_dir (e.g. "*.rst", "*.md"). Non-recursive — toctrees are one level deep by convention.parent_caption: human-readable heading shown above the toctree (Features, Modules, Decisions, etc.).maxdepth (optional): :maxdepth: option for the toctree. Default 1.exclude (optional): list of filename globs to exclude from the toctree. Default ["index.rst"] (never self-reference).{
"toctree_path": "/abs/path/to/target_dir/index.rst",
"files_included": ["csv_export", "jama_pull", "reqif_import"],
"files_modified": true
}
files_included contains stems (filename without .rst extension), in the order they appear in the emitted toctree (alphabetical).
files_modified:
true if the skill wrote a new index.rst or overwrote one with matching content (idempotent write).false if index.rst already existed with CONTENT MATCHING what this skill would have written — no-op.false PLUS a warning in the return if index.rst exists with different content — skill did not overwrite; caller must handle merge.Glob target_dir/<file_glob> non-recursively. Subtract exclude matches. Sort alphabetically by filename. Strip file extensions to produce toctree entries (Sphinx toctree entries omit .rst).
If zero files remain, FAIL: "no files matched <file_glob> under <target_dir>; nothing to index".
Emit content in this exact shape:
<parent_caption>
<underline of = characters, exact length of parent_caption>
.. toctree::
:maxdepth: <maxdepth>
<stem_1>
<stem_2>
<stem_3>
.. toctree::.:maxdepth: line and the first stem.If target_dir/index.rst does not exist → write the new content, return files_modified=true.
If it exists and its content (after normalizing line endings and trailing whitespace) exactly equals what would be written → no-op, return files_modified=false, warnings=[].
If it exists with different content → no-op, return files_modified=false, warnings include "index.rst exists with different content — not overwriting; delete manually or merge to regenerate".
Return the JSON shape per Output section.
No dedicated *-review atom exists for toctree emission; the operation is structural (write one index.rst listing N files) and its correctness is checked mechanically rather than via a prose-judgement review atom. This skill therefore performs an inline self-verification in Step 4 before returning:
toctree block resolves to an existing file under target_dir (no dangling references).index.rst contains exactly one .. toctree:: directive (no accidental duplication).If any check fails, do not write index.rst; return status: "failed" with evidence.
Coverage is mechanically enforced at plan level by pharaoh-quality-gate's orphan / link-completeness invariants plus sphinx-build -W itself (which fails on orphan RST files). See shared/self-review-invariant.md for the rationale.
target_dir does not exist → FAIL.target_dir is not a directory → FAIL.<target_dir>/index.rst into the project root's index.rst manually.*.md as file_glob. Sphinx's myst_parser must already be configured in the project for Markdown files to resolve.npx claudepluginhub useblocks/pharaoh --plugin pharaohBootstraps sphinx-needs into Sphinx projects without it by adding extension and need types to conf.py or ubproject.toml, enabling needs.json output. Handles version install/upgrade with confirmation.
Defines RST conventions for Scopy plugin docs: headings, toctree, labels, image placeholders, attribute tables, and index structure. Auto-loads during Scopy RST authoring.
Creates and maintains TYPO3 extension documentation following docs.typo3.org standards. Handles RST files, guides.xml, XLF translations, renders with Docker, and validates against official rules.