Groups hexdocs pages by kind and adds a manifest - #129
Merged
Merged
Conversation
The hexdocs sidebar groups the shipped pages under "How-to guides" (docs/guides/) and "Explanation" (docs/explanation/) where one "Guides" group held them all. The README and the CHANGELOG stay ungrouped at the top, main stays the README, and the API reference and package files do not change. Two how-to pages take "How to" titles: the two-vaults page and the scope-in-jobs page. Their files keep their names, and the link text in README.md and docs/README.md follows the new titles. Adds .claude/diataxis.md, the docs manifest the documentation tools read: where each kind of page lives, the audience, and that examples here are domain-free. Refs: ece-2fk9
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.
What changes
The hexdocs sidebar groups each shipped page by the kind of page it is,
in the family order, where one "Guides" group held them all:
docs/guides/.docs/explanation/moving-off-cloak.md.The README (still
main) and the CHANGELOG stay ungrouped at the top.The extras list, the package files and the API reference do not change;
no decision record, plan or other contributor path was ever an extra
here, and none is added.
Two how-to pages take "How to" titles; their files keep their names and
docs/guides/keeps its name:two-vaults-customer-and-agreement.md: "How to keep a customer scopeand an agreement scope in two vaults".
scope-in-jobs-and-projectors.md: "How to resolve the scope in jobsand projectors".
The link text for those two pages in
README.mdanddocs/README.mdfollows the new titles; every link target is unchanged. The two guide
tests read only the pages' code blocks, so the titles do not reach them.
.claude/diataxis.mdis new: the docs manifest the documentation toolsread (audience, where each kind of page lives, the contributor paths,
the executed snippets). Examples in this package are domain-free. It is
the generated file, byte for byte; neither prose line was changed.
No file under
lib/changes. No changelog fragment:changelog.d/README.mdexcludes documentation changes.Checks
mix qualitygreen on the committed tree, including the Docsstage (ExDoc warnings as errors) and the doc_links stage.
ungrouped; every
docs/guides/page under "How-to guides"; theexplanation page under "Explanation".
Review
Gate tier, the worker's own review round: docs configuration under the
size threshold, no contract surface.