Documentation site - #28
Merged
Merged
Conversation
The README documented roughly half of what the library does. Conventions,
decorators, interception and environment-conditional registration had no
documentation at all, there was no diagnostics reference despite the README
telling people to check for DM codes, and the trimming and AOT story — the
actual competitive position — was one sentence in the intro.
Sixteen pages under website/, built by VitePress:
guide getting started, modules, registering services, conventions,
scanning a package, decorators, interception, environments,
testing, trimming and AOT, troubleshooting
reference diagnostics, attributes, convention API, MSBuild properties
Dead internal links fail the build rather than shipping. The pages
cross-reference heavily, so a rename would otherwise rot links silently.
The README also had a code fence opened at the "Unit testing" section and not
closed until "Implementation", so the whole "Reporting a problem" section
rendered as a C# code block on GitHub and on every NuGet package page. Fixed,
and the shell commands inside that block moved to a shell fence.
Publishing needs Pages switched on by hand once — Settings, Pages, Source,
GitHub Actions. Until then the workflow builds and the deploy step fails, which
is the right way round: a broken site never replaces a working one.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01C56x6Vv6HJ6ArfqwKsuSb9
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
1 participant
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.
A VitePress site under
website/, published to GitHub Pages — plus a README bug that is live on every NuGet package page right now.Why
The README documented roughly half of what the library does. Conventions, decorators, interception and environment-conditional registration had no documentation at all. There was no diagnostics reference despite the README telling people to check for
DM####codes, and the trimming and AOT story — the actual competitive position against Scrutor and Castle — was one sentence in the intro.DependencyModules.Conventionsis also about to be published with a README that never says the word "convention".The README bug
A code fence opened at Unit testing & Mocking and did not close until Implementation, so the entire Reporting a problem section renders as a C# code block — on GitHub and on all five published NuGet pages. Three paragraphs of diagnostic advice, displayed as code. Fixed, and the shell commands inside that block moved to a
shellfence.Sixteen pages
Written against the code rather than from memory — the testing page in particular was written after reading
MockAttribute,InjectValuesAttribute,TestExportAttributeand the existing integration tests, so[InjectValues],[TestExport]and data-driven[ModuleTest]are documented as they actually behave.Several pages record traps found while building these features, including two I fell into myself: building a provider twice gives you two sets of singletons (which cost an hour chasing a phantom async-interceptor bug), and an intercepted service resolves as a generated wrapper so
Assert.IsType<Orders>fails where you would expect it to pass.Build
ignoreDeadLinks: false, so a dead internal link fails the build rather than shipping. The pages cross-reference heavily and a rename would otherwise rot links silently.Local search, dark mode, and a hero illustration that works on both themes without needing two files. Verified in a browser at 1440px in light and dark.
Deployment
.github/workflows/docs.yamlbuilds and deploys on pushes tomainthat touchwebsite/**. Repository settings are already correct — Pages build type isworkflow, thegithub-pagesenvironment is restricted tomain, and the site URL matches the configured base path. The workflow simply has to exist onmain, which is what merging this does.The workflow declares
pages: writeandid-token: writeexplicitly, which it needs because the repository default for the workflow token isread.Follow-ups, deliberately not in this PR
DependencyModules.Conventionsas available. Its install snippet will 404 until the package is published.🤖 Generated with Claude Code
https://claude.ai/code/session_01C56x6Vv6HJ6ArfqwKsuSb9