docs: library-integration guide + cross-links#114
Merged
Conversation
joshprice
force-pushed
the
docs-library-integration
branch
from
aef803b to
f888442
Compare
maennchen
reviewed
Apr 22, 2026
Adds `documentation/how_to/integrate-from-a-library.md` codifying
the three-part contract a library author follows to ship Clarity
content from inside their own library:
1. Module guarded by `Code.ensure_loaded?(Clarity.Content)` (or the
corresponding behaviour for introspectors, vertex types, and
lensmakers)
2. Registration via the library's `application/0` env under
`:clarity_content_providers` (or the equivalent key)
3. `{:clarity, "~> 0.4", optional: true}` in deps
Also:
- Wires a "How To" section into ExDoc via `extras:` so HexDocs
surfaces the guide with its own sidebar entry
- Adds a condensed rules summary at usage-rules/library-integration.md
pointing at the guide, for AI coding assistants
- Links to the guide from the README's "Third-Party Libraries"
section and from usage-rules/content-providers.md
- Clarifies when library-owned content belongs in the extension vs a
cross-cutting library such as ash_diagram
- Recommends `YourLibrary.Clarity.*` as the canonical namespace
(shorter than `ClarityContent.*`, leaves room for introspectors
and vertex types in the same tree)
- Points at `ash_diagram` and `ash_state_machine` as worked examples
joshprice
force-pushed
the
docs-library-integration
branch
from
f888442 to
85e8ad7
Compare
maennchen
approved these changes
Apr 22, 2026
…ests The "unknown task" warnings in the ack and nack handlers of Clarity.Server had their log strings swapped, so a stale ack was reported as a stale nack (and vice versa). Two tests in server_test.exs deliberately exercise the stale-ack path but never flushed the cast, so the warning leaked to the console intermittently depending on scheduling relative to ExUnit's capture_log scope. Wrap those calls in capture_log with a sync flush and assert the expected warning.
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
2 participants
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.
Adds usage-rules/library-integration.md codifying the three-part contract a library author follows to ship Clarity content from inside their own library:
Code.ensure_loaded?(Clarity.Content)application/0env under:clarity_content_providers(or:clarity_introspectors/:clarity_perspective_lensmakers){:clarity, "~> 0.4", optional: true}in depsAlso:
YourLibrary.Clarity.*as the canonical namespace (shorter thanClarityContent.*, leaves room for introspectors and vertex types in the same tree)