Add a README per example and an index in the root README - #39
Merged
Conversation
Fifteen example directories with no way to tell them apart without opening the source. Each now has a short README saying what it demonstrates, which packages it needs, how to run it, and which documentation page it follows. The root README groups them into a table so the repo is browsable from the top. The three ASP.NET Core examples all target the same doc page and differ only in hosting shape, so each README says how it differs from its siblings rather than repeating the same summary three times. Examples.slnx groups projects by area instead of one flat src folder. The src layout itself is unchanged, because moving directories would break every inbound link from the documentation for no gain. Part of #32
9 tasks
Three of the twelve package IDs don't match their repository name, so the map is explicit rather than derived: Autofac.Mvc5 lives in Autofac.Mvc, Autofac.WebApi2 in Autofac.WebApi, and Autofac.WebApi2.Owin in Autofac.WebApi.Owin. Every link is verified against the origin remote of the corresponding clone. Part of #32
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.
Part of #32
Proposed Changes
src/and no way to tell them apart without opening the source. Each now says what it demonstrates, which packages it needs, how to run it, and which documentation page it follows. Four or five lines each, not a design document.Examples.slnxgroups projects by area instead of a single flatsrcfolder.The
srcdirectory layout is deliberately unchanged. Moving directories would break all ten inbound links from the Documentation repo and gains nothing once the table exists.Two small judgment calls. The three ASP.NET Core examples share one doc page and differ only in hosting shape, so each README says how it differs from its siblings rather than repeating the same paragraph three times. And
ConfigurationExampleInterfaceandConfigurationExamplePluginget READMEs that say they are supporting libraries and point atConfigurationExample, since they'd otherwise look like examples someone forgot to document.Verification
Every
srcdirectory has a README, and all 15 projects are still in the solution — I diffed the project set before and after regrouping rather than trusting the file to look right.All 32 markdown links are checked programmatically. Relative links are resolved against the filesystem. The documentation links are validated against the
Documentationrepo by mapping eachreadthedocs.io/en/latest/<path>.htmlback todocs/<path>.rstand confirming the file exists, which catches a wrong page name without needing the network.The run instructions were executed rather than assumed. Both
/api/valuesexamples bindhttp://localhost:5000and return["value1","value2"], and the child lifetime scope example servesApplicationAon 5000 andApplicationBon 5001. I checked each log forHosting failedtoo, because a stale listener from an earlier run can answer curl and make a failed start look like a pass.dotnet build Examples.slnxstill succeeds, and pre-commit including markdownlint passes.