Building the Documentation
Open the documentation locally
Install the .NET 10 SDK and Python 3.9 or newer. Open PowerShell at the repository root and run:
.\Documentation\build.ps1 -Serve
The script restores the pinned DocFX tool, regenerates the API reference and sidebar,
builds the guides, and serves the result. Open
localhost:8080, and keep the terminal open while reading.
Press Ctrl+C to stop the server. Use -Port 8081 if port 8080 is occupied.
Do not use a bare docfx build after changing blocks or API associations: it skips
the repository's generated block navigation.
Build without serving
Run these commands in PowerShell from the repository root. You need Python 3.9 or newer (no additional Python packages), the .NET 10 SDK and a NuGet connection for the first tool and project restore.
.\Documentation\build.ps1
The script restores the repository's pinned DocFX 2.78.5, extracts API metadata,
automatically groups the API types by block, and writes the website to Documentation/_site.
The generated website is ignored by Git; only documentation sources should be tracked.
After a full build, Markdown-only changes can skip API extraction:
.\Documentation\build.ps1 -ArticlesOnly -Serve
macOS or another shell
PowerShell 7 can run the same script with pwsh ./Documentation/build.ps1.
Alternatively, from the repository root use the local tool directly:
cd Documentation
dotnet tool restore
dotnet tool run docfx metadata docfx.json
python3 generate_api_blocks.py
dotnet tool run docfx build docfx.json
dotnet tool run docfx serve _site --port 8080
The application and its dependencies must restore on the build host for API extraction.
After metadata exists, run the generator followed by docfx build to rebuild articles
and navigation. Use a full build after adding, removing or renaming C# types;
-ArticlesOnly uses the last extracted API metadata.
Publish with GitHub Pages
The repository includes .github/workflows/documentation-pages.yml. On every push to
main, GitHub Actions performs a clean full build, runs the documentation checks, and
deploys Documentation/_site to GitHub Pages. You can also start the workflow manually
from the repository's Actions tab.
After creating the GitHub repository and pushing main, enable the deployment once:
- Open Settings > Pages in the GitHub repository.
- Under Build and deployment, set Source to GitHub Actions.
- Open Actions > Publish documentation and run the workflow, or push a commit to
main. - Follow the deployment URL shown by the completed
Deploy documentationjob. GitHub also displays the public URL under Settings > Pages.
The workflow uses GitHub's Pages artifact deployment, so it does not create or maintain a
gh-pages branch. Generated HTML remains untracked, and the live site is replaced only after
the build and documentation checks pass. If the repository uses a default branch name other
than main, update the branch under on.push.branches in the workflow.
GitHub Pages availability for a private repository depends on the GitHub account or organization plan. If Settings > Pages is unavailable while the repository is private, publish the repository or use a plan that supports private-repository Pages.
Where to edit
- Edit guides in
Documentation/docsand their navigation indocs/toc.yml. - Edit individual block pages in
Documentation/docs/blocksand link them fromblock-catalogue.md. - Keep downloadable examples in
Documentation/examplesand diagrams inDocumentation/images. - Edit API comments in the C# source files.
- Edit the API introduction in
Documentation/api/index.md. - Edit site settings in
Documentation/docfx.json.
Generated metadata goes into ignored Documentation/_api and is published under
api/ in the website. The old generated YAML files under Documentation/api are
no longer build inputs. Do not edit generated metadata or HTML to update documentation.
Troubleshooting
- Old global DocFX: use
build.ps1, which selects the pinned local tool. DocFX 2.78.4 can fail to load the current MVVM source generator; 2.78.5 adds .NET 10 support. - Mobile workload errors or duplicate API members: metadata intentionally targets
only
MOSAIC/MOSAIC/MOSAIC.csprojatnet10.0. Do not replace this with an all-project wildcard: mobile variants compile the same source and require other frameworks. - File locked or user-mapped section open in
_site/toc.json: a background Git process was observed mapping this file and other generated output during a build. Keep_siteignored and untracked, so background Git comparisons do not read files while DocFX overwrites them. An ignore rule alone does not affect already tracked files. To check, rungit ls-files Documentation/_sitefrom the repository root: it should print nothing. Existing checkouts that still track the output can usegit rm -r --cached -- Documentation/_siteto remove it from the index while keeping local files; commit that tracking change together with the ignore rule. If the error returns with untracked output, identify the process holding the mapping before changing permissions or stopping applications. Administrator permissions do not release an existing mapping. - A lock in
_api: run only one full API build at a time and close tools holding generated metadata. Separate website output folders do not isolate API extraction. - NuGet restore fails: check network access and package-source credentials, then rerun.
- Warnings about XML comments or unresolved links: the site may still build; fix the referenced source comment or Markdown link. A successful build does not mean all documentation warnings have been resolved.
Keep the guides accurate
Write tutorials for students who know basic C# but have never used MOSAIC. Explain new terms before using them, state what to install or open, and give exact file locations and command working directories. Introduce one operation at a time and include a checkpoint showing what the reader should see. Keep optional UI work and advanced threading or lifetime details after the first working example.
Mark snippets as either complete files, complete pipelines or integration fragments. Give every fragment a location and explain any names it depends on. Reuse downloadable source in the page where possible, and compile or exercise the same files in tests. Explain which work MOSAIC already performs and which registration is still manual. Keep supported older formats documented as compatibility options; label historical porting notes and their old verification counts so readers do not mistake them for setup steps.
When changing a block, check its parameter reader, exporter, factory aliases and palette hints together. Update its reference page in the same change. Prefer complete runnable examples with expected output; mark partial snippets as fragments. Explain current behavior and actionable limits rather than leaving historical bug reports in setup instructions.
Automatic API grouping
Use build.ps1 after adding a block. You do not need to add a navigation entry.
The build generates the ignored Documentation/api-blocks.json from fresh API metadata:
- Concrete classes that inherit from
BaseBlockbecome block entries, including developer templates. BlockCatalogsupplies the display name and category;BlockFactorysupplies searchable aliases.BlockTemplateSelectorassociates the model with its card and view model. Matching names such asExampleViewModel,ExampleCardViewandExampleConfigViewadd other associated UI types. A model namedExampleBlockalso matches theExamplestem.- Nested types and types declared in the same source files become related types.
- An existing block guide supplies its established title and link. Blocks without a guide still appear, with a link to the catalogue. Write the guide separately; it is not generated.
The source reader supports the repository's current catalogue, factory and selector declaration patterns, including multiline entries and qualified names. It does not infer arbitrary C# construction logic or every dependency. Unassociated types remain in Shared APIs.
For unusual associations, edit Documentation/api-block-overrides.json, keyed by the
model's full API UID. viewModel and view replace inferred associations; related adds
exact helper UIDs; relatedNamespaces adds all types in a dedicated helper namespace.
Shared helpers can belong to more than one block. For example:
{
"MOSAIC.Models.SignalProcessing.Filter": {
"relatedNamespaces": ["MOSAIC.Components.SignalProcessing"]
}
}
Ambiguous naming matches require an explicit association. Missing override types stop
the build with a clear error, so update overrides when moving or deleting those classes.
Do not edit api-blocks.json directly or use a bare docfx build after changing associations;
the build script runs the generator at the correct point.
Run python Documentation/test_generate_api_blocks.py to check discovery behavior,
or python Documentation/generate_api_blocks.py --check to detect a stale generated mapping.
After building, run python Documentation/check_docs.py from the repository root to check
guide links, downloadable JSON and catalogue coverage against factory registrations.
Review the first-pipeline page and catalogue in a browser as well; link checks do not test
hardware or certify every parameter description.