daslib/rst_comment: add --detail_output flag for non-default doc trees#2640
Merged
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a consumer-facing CLI option to the rst_comment comment reader so downstream projects can redirect where per-symbol detail/*.rst snippets are written, without changing the default daslang doc build behavior.
Changes:
- Add
--detail_output Yflag to write detail snippets toY/detail/. - Keep existing
--docs_output Xbehavior (X/index/detail/) as a fallback when the new flag is not present. - Preserve the default output location when neither flag is provided.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Lets a consumer (e.g. dasImgui's utils/imgui2rst.das, or any other
project that vendors daslang's RST tooling) redirect the per-function
detail snippets at a custom location matching its own topic_root.
`--detail_output Y` writes per-symbol details to `Y/detail/`, matching
the natural read path `{topic_root}/detail/...` so the consumer can
set `topic_root = Y` and have writes and reads line up without the
existing `--docs_output X` flag's `/index/` segment (which is
load-bearing for the Eden / dasimgui-game style invocation pattern
that pairs `--docs_output X` with `topic_root = X/index`).
Default behavior (no flag) and `--docs_output` semantics are
unchanged. daslang's own das2rst doesn't pass either flag, so the
default daslang doc build is byte-identical.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
borisbat
force-pushed
the
bbatkin/rst-comment-detail-output
branch
from
ff79ec1 to
85fffe0
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
--detail_output YCLI flag todaslib/rst_comment.das's comment reader. When set, per-function//!detail snippets are written toY/detail/instead ofget_das_root() + /doc/source/stdlib/generated/detail/.utils/imgui2rst.das, dasimgui-game's doc build) route detail snippets at its owntopic_root. Settopic_root = Yand--detail_output Y; reads at{topic_root}/detail/...and writes atY/detail/line up cleanly — no/index/segment required.--docs_output X(which appends/index/detail/, load-bearing for Eden / dasimgui-game style invocations that pair--docs_output Xwithtopic_root = X/index) is unchanged.das2rstdoesn't pass either flag, so the daslang doc build is unaffected.Test plan
das2rstregeneratesdoc/source/stdlib/generated/detail/to the same content as master (no diff in tracked detail files for daslang's own doc tree).utils/imgui2rst.das -- --detail_output modules/dasImgui/doc/source/stdlib/generatedlands per-function details in the correct dasImgui-side tree;sphinx-build -Won the dasImgui doc tree builds clean with no broken substitutions.Notes for review
daslib/rst_comment.daswrite_to_detailmethod.borisbat/dasImgui).🤖 Generated with Claude Code