Conversation
Treat ~/ as an explicit documentation-root marker while preserving standard semantics for site-root and document-relative URLs. Normalize marked paths without allowing them to escape the documentation root, update both resolution strategies, and expand routing tests for the new behavior.
Rename the relative and absolute URL context managers and the documentation URL transformer to reflect their responsibilities. Rename DocumentUrlContext.IsRoot, RootUrl, TryTransformSiteRelativeUrl, and IsSiteRelativeUrl to IsDocumentationRoot, DocumentationRootUrl, TryResolveUrl, and TryParseDocumentationRelativeUrl, and update files, XML references, construction sites, and tests consistently.
Place the subpath before the full path so the call order follows the predicate's natural reading. Update the topic lookup, tests, and XML documentation without changing matching behavior.
- Add abstract ResolveFromDocumentationRoot method for core resolution logic - Make TryResolveUrl concrete in base class to eliminate duplication - Update DocumentAddressProvider.ToDocumentUrl to use new method directly - Add comprehensive tests for ResolveFromDocumentationRoot - Improve documentation for clarity and correctness This change simplifies the API by removing the need to artificially prepend '~/' markers when callers already know they have documentation-relative URLs. Subclasses now only implement the resolution strategy, not parsing logic.
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
2 participants
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.
This pull request introduces several important changes to the documentation pipeline, focusing on improving terminology consistency, refactoring URL transformation infrastructure, and updating versioning. The main themes are: a refactor of URL context and transformer classes for clarity and extensibility, terminology updates from "site-root-relative" to "documentation-root-relative", and a breaking version bump to 3.0.0.
URL Transformation Infrastructure Refactor:
RelativeToAbsoluteUrlNormalizertoAbsoluteUrlContextManager, updated its internal class and methods, and clarified its purpose as converting documentation-root-relative URLs to absolute URLs using a configurable documentation root. Updated constructor and method parameter names and XML docs accordingly. (src/Routing/AbsoluteUrlContextManager.cs) [1] [2] [3]DocumentAddressProviderto useAbsoluteUrlContextManagerandRelativeUrlContextManagerinstead of the old normalizer classes, and changed the internal method to resolve documentation-root-relative paths. (src/Routing/DocumentAddressProvider.cs) [1] [2]Terminology and Documentation Consistency:
IDocumentationContextandDocumentationContext. (src/IDocumentationContext.cs,src/DocumentationContext.cs) [1] [2] [3]DocumentationContextto beDocumentationUrlTransformerinstead ofContextAwareUrlTransformer, reflecting the new naming and focus. (src/DocumentationContext.cs)Bug Fix:
TopicCollection.TryFindBySubpathto correctly check if the given subpath is a subpath of the topic's source file path. (src/Collections/TopicCollection.cs)Versioning:
3.0.0in the project file to indicate a breaking change. (src/Kampute.DocToolkit.csproj)Other:
.github/copilot-instructions.mdfile, which previously contained project architecture and contribution guidelines.src/DocumentationContext.cs,src/Routing/DocumentAddressProvider.cs) [1] [2]System.Runtime.CompilerServicesusing. (src/Routing/DocumentUrlContext.cs)These changes modernize and clarify the documentation generation infrastructure, making it easier to extend and maintain, and ensure terminology is consistent across the codebase.