Repository navigation
Docs: a self-publishing DocFX site (GitHub Pages) and a README that sells it - #35
Merged
Merged
Conversation
- docsite/: DocFX 2.81 (modern template) site with a landing page, nine articles and the API reference generated from the XML docs of Core, Channel, Dataflow and MSSqlClient (net10.0). SqlClient is not included: it declares the same type names as MSSqlClient in the same namespace. - docsite/samples: a net10.0 project (SQLite in memory, Dapper for the side-by-side) that every article snippet is copied from; Program.cs runs 35 checks. - .github/workflows/docs.yml: builds on every push to master, pull request and manual run; deploys only from master. Warnings are listed in the job summary and never block; an error or a sample that does not compile does. - .config/dotnet-tools.json pins DocFX 2.81.0; generated output is git-ignored. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
The 1344 px logo rendered at full size in the navbar; the site now uses a 40 px logo and a 32 px favicon. Article wording is tightened against the code (AddParamIf, async twins, buffering helpers). Region names in BeforeAfter.cs no longer clash with DapperComparison.cs. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Leads with a plain ADO.NET versus Open.Database.Extensions comparison (line counts taken from the compiled snippets), measured and honestly worded performance bullets, the factory and connection forms of the expressive commands, Map<T>() on matching names, transactions, an install table and absolute links to the docs site. Every code block is copied from docsite/samples, which the docs workflow compiles and runs. Corrects the description of the Open.Database.Extensions meta-package (last published 9.0.3) and of the legacy SqlClient package. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Its own commit so it can be dropped. The repository URL is unchanged. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
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 this does
Gives the library a documentation site that rebuilds and redeploys itself on every push to master, and a README that sells the library instead of cataloguing it.
.github/workflows/docs.yml: runs on every push tomaster(no path filter), builds on pull requests (no deploy), and can be run by hand. Warnings never block a deploy and are listed in the job summary. An error (library build, a docs sample that no longer compiles, a DocFX error) fails the run, and then the previously published site stays live. DocFX is pinned to 2.81.0 in.config/dotnet-tools.json; the five actions are pinned to their current major versions. No Dependabot, no schedule.docsite/: DocFXmoderntemplate, landing page with an architecture diagram (one SVG, light and dark), nine articles, and an API reference generated from the XML docs for Core, Channel, Dataflow and MSSqlClient (350 pages, search included). Every code sample in the articles and the README comes from a small compiled project,docsite/samples, which runs 35 checks and is built by the workflow, so the docs cannot show code that does not compile.docsite/CONTRIBUTING-DOCS.mdsays where each kind of documentation lives (12 lines).README.md: rewritten as a pitch. A before/after of plain ADO.NET versus one fluent command (20 lines versus 5, counted from the compiled snippets), three measured and honestly worded speed bullets, expressive commands in factory and connection form,Map<T>(), install table. All links are absolute (the README is packed into the NuGet packages). Performance wording follows the independent preview01 re-run, not the old claims.Source/Directory.Build.props:PackageProjectUrlpoints at the docs site (own commit, easy to drop).One-time step after merging (the only thing to remember)
Docsworkflow once (Actions > Docs > Run workflow); after that every push to master republishes by itself.Until step 2, the current site keeps serving from
master:/docs(this PR does not delete it), and the first run on master will stop atconfigure-pagesbecause Pages is still on the legacy source. That is expected and harmless. A follow-up PR deletes the olddocs/output once the first deploy is green.Verified locally
dotnet docfx docsite/docfx.json: 0 errors, 315 warnings, 16 s. 307 of them are "duplicate parameter" warnings from overloads that combine<inheritdoc>with their own<param>tags in the XML docs; a separate comment-quality branch fixes those.csblock identical to a compiled sample region.Not provable until the first GitHub run
The Pages deployment itself,
upload-pages-artifacton a Windows runner,setup-dotnetresolving 10.0.x, and the README diagram URL (it resolves only after merge). TheDocscheck on this PR builds everything except the deploy, so it is the first real test on GitHub's runner.Screenshots of the built site (landing page and an API page) are attached below.
🤖 Generated with Claude Code