Working on the documentation

The documentation uses DocFX to combine Markdown guides with API pages generated from src/FinanceSharp/FinanceSharp.csproj. The root .config/dotnet-tools.json pins the same tool version for local builds and continuous integration.

Build and preview

Install the .NET 10 SDK and PowerShell 7, then run this command from the repository root for the complete build, text exports, validation, and preview:

pwsh -File eng/Build-Docs.ps1 -Serve

Open http://localhost:8080. Stop the preview server with Ctrl+C. Re-run the build after changing a guide or an API comment.

On Windows, docs\serve.bat runs the same workflow. It can be invoked from any working directory.

To run each stage manually from the repository root:

dotnet tool restore
dotnet restore src/FinanceSharp/FinanceSharp.csproj
$config = & ./docs/scripts/New-DocfxConfiguration.ps1 -SiteDirectory docs/_site
dotnet tool run docfx -- $config
./docs/scripts/Export-LlmDocs.ps1 -SiteDirectory docs/_site
./docs/scripts/Test-Documentation.ps1 -SiteDirectory docs/_site
dotnet tool run docfx -- serve docs/_site --port 8080

The generated configuration places API metadata in a new, unique directory under artifacts/docs/ for each build. Removed types cannot survive from an older API generation. Pass a new -SiteDirectory to the build driver to verify an entirely fresh site without touching a preview that is already running.

The DocFX metadata step selects net10.0, Release, and x64 and disables package generation. The library's .NET 8 and .NET 10 targets share this API reference. Compilation errors fail the documentation build. Existing XML-comment warnings remain visible in the build log and should be fixed alongside the affected source.

Edit the right files

Content	Source
Home page	docs/index.md
Top navigation	docs/toc.yml
Guides and their navigation	docs/articles/
API descriptions	XML comments in src/FinanceSharp/
API landing page and namespace overviews	docs/api/index.md, docs/api/overwrites/
Build settings	docfx.json
FinanceSharp theme overrides	docs/templates/financesharp/public/
Export and validation scripts	docs/scripts/

API YAML generated by a direct docfx.json invocation under docs/api/, isolated builds under artifacts/docs/, and the rendered site under docs/_site/ are ignored by Git. Do not edit or commit them. Add new guides to docs/articles/toc.yml, use relative Markdown links for site pages, and use DocFX cross-references such as <xref:FinanceSharp.DoubleArray> for API types.

DocFX's default filter includes public APIs and excludes implementation details. FinanceSharp does not add a custom filter that hides its public types. Use an API overwrite when a namespace needs an overview that cannot live in a type's XML comment. The checked-in namespace overwrites are applied during the site build; they do not replace or edit application source.

What the complete build produces

The modern template provides search, light and dark themes, mobile navigation, copyable examples, API signatures, and links to source. FinanceSharp supplies its own CSS, GitHub navigation link, logo, and favicon. The build also emits a sitemap, an xref map for other DocFX sites, llms.txt, llms-full.txt, and robots.txt.

The text exports use the completed DocFX manifest and rendered articles. They include every generated API page and member description as well as every guide, with no fixed API list or truncation to a handful of types. Relative article links become links to the configured public site. robots.txt describes crawling at a host root; on a GitHub Pages project URL, the host's root policy takes precedence.

Validation checks required outputs, actual API declarations, source links, the search index, every local HTML link and fragment, and both text exports. Compilation errors and missing output fail the build; source XML-comment warnings remain visible.

Build the complete site before opening a pull request, then check changed pages, navigation, and links in the preview. The GitHub documentation workflow validates the site and handles publication to GitHub Pages when publishing is configured.

See the contribution guide for the wider development workflow and the maintainer guide for publication setup.