Feature/repo tools#3
Merged
Merged
Conversation
This commit introduces comprehensive user documentation for the Invex.FileSystem library. It includes getting started instructions, conceptual overviews, API reference, and detailed guides on key features such as rooted paths, path providers, path markers, and file transform scopes. The documentation is structured for use with DocFX, with the necessary `docfx.json` configuration and corresponding markdown files added.
There was a problem hiding this comment.
Pull request overview
This PR improves repository tooling and developer guidance for Invex.FileSystem by adding DocFX documentation infrastructure, public API surface snapshot testing, workflow automation (docs publishing + prerelease cleanup), and some build/Atom refactors to use shared RepoUtils modules.
Changes:
- Added a DocFX site scaffold (DocFX config, conceptual docs, TOCs, API landing page, root index redirect).
- Added/updated CI workflows to build & publish docs and to unlist old prerelease packages; aligned injected env var naming for PR number.
- Introduced a public API surface snapshot test and updated build/analyzer dependencies (RepoUtils analyzers/test utils, package bumps).
Reviewed changes
Copilot reviewed 37 out of 37 changed files in this pull request and generated 9 comments.
Show a summary per file
| File | Description |
|---|---|
| toc.yml | Adds the top-level DocFX TOC entries. |
| index.md | Adds DocFX site landing/redirect page. |
| docfx.json | Adds DocFX build configuration and site metadata. |
| api/index.md | Adds API reference landing page. |
| docs/toc.yml | Adds conceptual-docs TOC. |
| docs/introduction.md | Adds conceptual introduction page. |
| docs/getting-started.md | Adds installation + DI wiring guide. |
| docs/rooted-paths.md | Adds RootedPath conceptual documentation. |
| docs/path-providers.md | Adds provider-chain documentation and examples. |
| docs/path-markers.md | Adds path-marker documentation and examples. |
| docs/transform-scopes.md | Adds transform-scope documentation and behavior reference. |
| docs/testing.md | Adds testing guidance and examples. |
| README.md | Updates license links to GitHub URL. |
| Invex.FileSystem.slnx | Groups src/tests projects into folders. |
| src/Invex.FileSystem/Invex.FileSystem.csproj | Swaps public API analyzer package and bumps Microsoft.Extensions.* abstractions. |
| src/Invex.FileSystem/RootedFileSystem.cs | Refines XML docs; documents PathProviders property. |
| src/Invex.FileSystem/RootedPath.cs | Refines XML docs for DirectoryName semantics. |
| src/Invex.FileSystem/IPathMarker.cs | Adjusts XML doc wording. |
| src/Invex.FileSystem/FileSystemHostExtensions.cs | Clarifies provider tie-break behavior in docs. |
| src/Invex.FileSystem/TransformFileScope.cs | Expands XML docs and improves <inheritdoc> usage. |
| src/Invex.FileSystem/TransformMultiFileScope.cs | Expands XML docs and improves <inheritdoc> usage. |
| src/Invex.FileSystem/TransformFileScopeExtensions.cs | Documents cancellation-token behavior for fluent overloads. |
| tests/Invex.FileSystem.Tests/Invex.FileSystem.Tests.csproj | Adds RepoUtils test utils; bumps test package versions. |
| tests/Invex.FileSystem.Tests/_usings.cs | Adds global using for RepoUtils test utils. |
| tests/Invex.FileSystem.Tests/PublicApiSurfaceTests.cs | Adds Verify-based public API surface snapshot test. |
| tests/Invex.FileSystem.Tests/PublicApiTests.VerifyPublicApiSurface.verified.txt | Adds verified public API snapshot output. |
| .github/workflows/Validate.yml | Renames PR-number env var to github-pull-request-number. |
| .github/workflows/Build.yml | Adds BuildDocs/PublishDocs jobs and artifact plumbing. |
| .github/workflows/Dependabot Enable auto-merge.yml | Removes redundant permissions; injects PAT + renamed PR-number env var. |
| .github/workflows/Cleanup Prereleases.yml | Adds manual prerelease-unlisting workflow. |
| .github/copilot-instructions.md | Adds comprehensive contributor/agent guidance and repo conventions. |
| _atom/_atom.csproj | Swaps Atom/GitVersion modules to Invex equivalents and adds RepoUtils Atom module. |
| _atom/IBuild.cs | Refactors build definition: breaking-change file list, prerelease unlisting targets, DocFX targets, workflow wiring. |
| _atom/ICheckPrForBreakingChanges.cs | Removes obsolete local implementation (migrated to shared module). |
| _atom/IApproveDependabotPr.cs | Removes obsolete local implementation (migrated to shared module). |
| _atom/IApiSurfaceHelper.cs | Removes obsolete local helper (migrated to shared module). |
| _atom/_usings.cs | Removes obsolete global usings file (migrated to shared module / explicit usings). |
Comment on lines
+1
to
+4
| - name: Docs | ||
| href: docs/ | ||
| - name: API Reference | ||
| href: api/ |
| If no provider recognizes a key, `GetPath` throws `InvalidOperationException`: | ||
|
|
||
| ``` | ||
| Could not locate path for key 'Artifcats' |
|
|
||
| Target PublishDocs => | ||
| t => t | ||
| .DescribedAs("Publishes the DocFX documentation to Github Pages.") |
Comment on lines
+52
to
+54
| RootedPath csproj = fs.GetPath("Root") / "src" / "App" / "App.csproj"; | ||
| Assert.True(csproj.FileExists); | ||
| ``` |
|
|
||
| await using (await TransformFileScope.CreateAsync(file, c => c.Replace("1.0.0", "2.0.0"))) | ||
| { | ||
| Assert.Contains("2.0.0", mock.File.ReadAllText(file)); |
| } | ||
|
|
||
| // Restored after dispose. | ||
| Assert.Contains("1.0.0", mock.File.ReadAllText(file)); |
Comment on lines
+22
to
+23
| Assert.True(path.FileExists); | ||
| Assert.Equal("file.txt", path.FileName); |
Comment on lines
+15
to
+16
| using System.IO.Abstractions.TestingHelpers; | ||
|
|
| namespace Invex.FileSystem.Tests; | ||
|
|
||
| [TestFixture] | ||
| public class PublicApiTests |
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.
This pull request introduces several improvements and infrastructure updates to the Invex.FileSystem repository, focusing on developer guidance, workflow automation, and minor codebase cleanups. The most significant changes are the addition of comprehensive Copilot instructions, enhancements to GitHub Actions workflows (including new documentation build and cleanup jobs), and the removal of obsolete or redundant code from the Atom build definition.
Documentation and Developer Guidance:
.github/copilot-instructions.mdfile with architecture overview, design rules, conventions, and workflow instructions for contributors and AI agents.README.mdto use direct links to the MIT license on GitHub, improving clarity and accuracy. [1] [2]GitHub Actions Workflow Enhancements:
BuildDocsandPublishDocsjobs to.github/workflows/Build.ymlfor automated documentation building and publishing, triggered as part of the CI pipeline..github/workflows/Cleanup Prereleases.ymlworkflow to unlist old prerelease NuGet packages below a specified stable version, supporting repository hygiene.pull-request-number→github-pull-request-number). [1] [2]Dependabot Enable auto-merge.yml.Build System and Codebase Maintenance:
_atom/IBuild.cs:IDocFxHelper) and package unlisting (INugetPackageUnlistHelper), and provided new parameters for prerelease cleanup. [1] [2].verified.txtfiles undertests/as the source of truth for breaking change detection.Invex.FileSystem.slnxto explicitly group source and test projects under/src/and/tests/folders.Code Cleanup:
_atom/IApiSurfaceHelper.csand_atom/IApproveDependabotPr.cs, streamlining the Atom build module. [1] [2]References: