Skip to content

Add a README per example and an index in the root README - #39

Merged
tillig merged 2 commits into
mainfrom
feature/navigation
Sep 1, 2026
Merged

Add a README per example and an index in the root README#39
tillig merged 2 commits into
mainfrom
feature/navigation

Conversation

@tillig

@tillig tillig commented Sep 1, 2026

Copy link
Copy Markdown
Member

Part of #32

Proposed Changes

  • A README per example. Fifteen directories under 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.
  • An index table in the root README, grouped into ASP.NET Core, hosting and core features, and .NET Framework, so the repo is browsable from the top.
  • Examples.slnx groups projects by area instead of a single flat src folder.

The src directory 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 ConfigurationExampleInterface and ConfigurationExamplePlugin get READMEs that say they are supporting libraries and point at ConfigurationExample, since they'd otherwise look like examples someone forgot to document.

Verification

Every src directory 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 Documentation repo by mapping each readthedocs.io/en/latest/<path>.html back to docs/<path>.rst and confirming the file exists, which catches a wrong page name without needing the network.

The run instructions were executed rather than assumed. Both /api/values examples bind http://localhost:5000 and return ["value1","value2"], and the child lifetime scope example serves ApplicationA on 5000 and ApplicationB on 5001. I checked each log for Hosting failed too, because a stale listener from an earlier run can answer curl and make a failed start look like a pass.

dotnet build Examples.slnx still succeeds, and pre-commit including markdownlint passes.

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
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
@tillig
tillig merged commit 5f76370 into main Sep 1, 2026
8 checks passed
@tillig
tillig deleted the feature/navigation branch September 1, 2026 18:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant