Interface IDocFxHelper

Namespace

Invex.RepoUtils.Atom.Module.Helpers

Assembly

Invex.RepoUtils.Atom.Module.dll

Provides functionality for generating, serving, and publishing DocFX documentation for the repository. The helper builds the static documentation site, can host it locally for previewing, and publishes the generated output to a project's gh-pages branch for GitHub Pages hosting.

public interface IDocFxHelper : IDotnetCliHelper, IGitHubHelper, ISetupBuildInfo, IBuildInfo, IVariablesHelper, IReportsHelper, IBuildAccessor

Inherited Members

IDotnetCliHelper.ConfigureHostBuilderFromIDotnetCliHelper(IHostApplicationBuilder)

IDotnetCliHelper.DotnetCli

IGitHubHelper.GitHubToken

ISetupBuildInfo.SetupBuildInfo

IBuildInfo.BuildName

IBuildInfo.BuildId

IBuildInfo.BuildVersion

IBuildInfo.BuildTimestamp

IBuildInfo.BuildSlice

IVariablesHelper.WriteVariable(string, string, CancellationToken)

IReportsHelper.AddReportData(IReportData)

IBuildAccessor.GetService<T>()

IBuildAccessor.GetServices<T>()

IBuildAccessor.GetParam<T>(Expression<Func<T>>, T, Func<string, T>)

IBuildAccessor.Services

IBuildAccessor.Logger

IBuildAccessor.RootedFileSystem

IBuildAccessor.ProcessRunner

Fields

GeneratedDocsArtifactName

The name of the build artifact (and corresponding output sub-directory) that contains the generated DocFX site. Used both as the destination folder under the publish directory and as the artifact name resolved under the artifacts directory when publishing.

public const string GeneratedDocsArtifactName = "GeneratedDocs"

Field Value

string

Methods

BuildDocFxDocs(IEnumerable<RootedPath>?, CancellationToken)

Builds the DocFX documentation site and copies the generated output into the publish directory under GeneratedDocsArtifactName.

Task BuildDocFxDocs(IEnumerable<RootedPath>? projectsToPrebuild = null, CancellationToken cancellationToken = default)

Parameters

projectsToPrebuild IEnumerable<RootedPath>

An optional collection of projects to build in Release configuration before running DocFX. This ensures any metadata DocFX extracts from the compiled assemblies and XML documentation is up to date. When null, no projects are pre-built.

cancellationToken CancellationToken

A token used to cancel the operation.

Returns

Task

Remarks

On .NET 10 or newer the tool is executed directly via dotnet tool exec docfx. On earlier runtimes the DocFX global tool is updated/installed first and then invoked via dotnet docfx. The site is generated into the _site directory beneath the Atom root before being copied to the publish directory.

CopyDirectory(RootedPath, RootedPath)

Copies all files and subdirectories from a source directory to a destination directory.

Task CopyDirectory(RootedPath sourceDirectory, RootedPath destinationDirectory)

Parameters

sourceDirectory RootedPath

The source directory.

destinationDirectory RootedPath

The destination directory.

Returns

Task

ForceDeleteDirectory(string)

Recursively removes read-only attributes and deletes a directory. Git object files are marked read-only, so a plain Directory.Delete fails.

void ForceDeleteDirectory(string path)

Parameters

path string

The path of the directory to delete.

PublishDocFxDocsToGithub(string, string, CancellationToken)

Publishes a previously generated DocFX site to the repository's gh-pages branch, making it available via GitHub Pages.

Task PublishDocFxDocsToGithub(string githubToken, string generatedDocsArtifactName, CancellationToken cancellationToken = default)

Parameters

githubToken string

The GitHub token used to authenticate the push. When the remote uses HTTPS, the token is injected into the remote URL as an x-access-token credential.

generatedDocsArtifactName string

The name of the artifact (under the artifacts directory) that contains the generated site to publish, typically GeneratedDocsArtifactName.

cancellationToken CancellationToken

A token used to cancel the operation.

Returns

Task

Remarks

The site is published by creating a fresh orphan gh-pages branch in a temporary directory, committing the generated files, and force-pushing to the origin remote. The temporary checkout is always removed once the operation completes, even on failure.

Exceptions

StepFailedException

Thrown when the generated site artifact does not exist, or when the origin remote URL cannot be determined.

ServeDocFxDocs(CancellationToken)

Serves the generated DocFX site locally for previewing, hosting it at http://localhost:8080 until the operation is cancelled.

Task ServeDocFxDocs(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

A token used to stop the local server. Cancellation is handled gracefully and results in the server shutting down without surfacing an error.

Returns

Task

Remarks

This serves the contents of the _site directory beneath the Atom root, so BuildDocFxDocs(IEnumerable<RootedPath>?, CancellationToken) should be run beforehand to ensure the site exists.