Docs: qualify APIs by assembly instead of prefixing the namespace - #65
Merged
Conversation
The upstream branch reworked the UID prefix into a distinct assembly component, following review feedback on dotnet/docfx#11090, so this switches to it: linq2db.Tools.LinqToDB.Tools.Activity.ActivityStatistics -> linq2db.Tools::LinqToDB.Tools.Activity.ActivityStatistics `assemblyUidPrefixes` becomes `assemblyUids`, and since every prefix here was already the assembly's own name, the map collapses to a plain list. `uidPrefixOverride` becomes `assemblyUidOverride` on the four EntityFrameworkCore entries, which still need it because they all build `linq2db.EntityFrameworkCore`. What this fixes on the site: the prefix used to be joined to the namespace with a dot and used as its display name, so pages read as namespaces that do not exist. Now: - `Namespace linq2db.Tools.LinqToDB.Tools.Activity` reads `Namespace LinqToDB.Tools.Activity (linq2db.Tools)`. - The namespace a type reports and the namespace page it links to agree; before, a type page said `LinqToDB.Tools.Activity` while the page behind that link was titled with the made up name. - Table of contents labels name the real namespace and the assembly it comes from, so the `LinqToDB` declared by both `linq2db` and `linq2db.Tools` is now `LinqToDB (linq2db)` and `LinqToDB (linq2db.Tools)` instead of two invented namespaces. Page URLs change once more, as the file name carries `--` where the UID has `::`. Two hand written xrefs in the articles named the old prefixed UIDs and are updated; they were the only ones. docfx/ rebuilt from fix/8966-uid-prefixes (dd95c86d9). The custom Roslyn 5.6.0 commit is gone: upstream took that bump in dotnet/docfx#11047, so the vendored build is now the upstream branch unmodified. Build output: 0 errors, 2389 API files, 2407 HTML pages, and 6 docfx warnings, all pre-existing (5 `InvalidFileLink` from Microsoft docs relative links in linq2db's XML comments, 1 `InvalidBookmark` from a `#remarks` anchor). No `DuplicateUids` and no `UidNotFound`. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
docfx/ rebuilt from fix/8966-uid-prefixes (9907932d6), which folds in a code review of the assembly component design: - a repeated or empty entry in the `assemblyUids` array is reported as an invalid entry instead of throwing out of the JSON converter - with `outputFormat: apiPage` or `markdown`, two assemblies resolving to one component now share a single table of contents node - the new table of contents ordering is skipped when no assembly is qualified, so it cannot affect a project that does not use this No change to `source/docfx.json` and no change to the output: 0 errors, 2389 API files, 2407 HTML pages, and the same 6 pre-existing docfx warnings. Co-Authored-By: Claude Opus 5 (1M context) <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
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.
Follow-up to #64. The upstream branch reworked the UID prefix into a distinct assembly component after review feedback on dotnet/docfx#11090, so this switches the site to it:
Why
In #64 the prefix was joined to the namespace with a dot and used as its display name, so the site read as namespaces that do not exist. Fixed here:
Namespace linq2db.Tools.LinqToDB.Tools.ActivityNamespace LinqToDB.Tools.Activity (linq2db.Tools)LinqToDB.Tools.Activity, linked to a page titled with the made up nameLinqToDBnamespace of two assembliesLinqToDB (linq2db)andLinqToDB (linq2db.Tools)Config
assemblyUidPrefixes->assemblyUids. Every prefix here was already the assembly's own name, which is the new default, so the map collapses to a plain list.uidPrefixOverride->assemblyUidOverrideon the four EntityFrameworkCore entries, which still need it because they all buildlinq2db.EntityFrameworkCore.Heads up
--where the UID has::, e.g.api/linq2db.tools/linq2db.Tools--LinqToDB.Tools.Activity.html.articles/general/databases.md,articles/sql/Bulk-Copy.md). They were the only ones — the build reported them asUidNotFoundbefore the fix.docfx/is rebuilt fromfix/8966-uid-prefixes(dd95c86d9) and no longer carries a custom Roslyn commit: upstream took that bump in deps: Update roslyn package versions to 5.6.0 dotnet/docfx#11047, so the vendored build is the upstream branch unmodified.Build
0 errors, 2389 API files, 2407 HTML pages — the same counts as before. 6 docfx warnings, all pre-existing: 5
InvalidFileLinkfrom Microsoft docs relative links in linq2db's XML comments, 1InvalidBookmarkfrom a#remarksanchor. NoDuplicateUids, noUidNotFound.🤖 Generated with Claude Code