Updates for FHIR Foundation#181
Merged
Merged
Conversation
Migrate docs/*.md, specs/*.md, and src/Fhir.CodeGen.Packages/docs/ into a single top-level docs/ tree (articles/ + specs/) with new index.md, README.md, and toc.yml. The new tree is additive: docfx/articles/ remains intact so the existing (broken-but-buildable) DocFX inputs are still parseable until Phase 2 cuts over. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…l docs/
Phase 2 of the docs-site restoration plan. Rewrites docfx/docfx.json to
generate API reference for the current 8-project Fhir.CodeGen.* library
set only (no CLI types, no SQLiteGenerator, no performance-test-cli, no
*.Tests). Adds three content roots: api/ (generated), ../docs (new
authoring root from Phase 1), and cli-generated/ (Phase 3 emitter
output, gitignored). Sets _appTitle and _gitContribute metadata to
FHIR/fhir-codegen.
Cutover deletes the old docfx/articles/, docfx/index.md, and
docfx/toc.yml that were superseded by docs/ in Phase 1.
Fixes four pre-existing source XMLDoc bugs that surfaced during the
docs build:
- PackageLoader.cs:1523, ServerConnector.cs:825 - cref `FhirCache`
pointed at a removed type; replaced with the enclosing class name.
- PackageManifest.cs:88 - unescaped `<filename>` in a
`<remarks>` block; escaped to `<filename>`.
- RegistryCatalogRecord.cs:22,43 - unescaped `&` in two example
URLs; escaped to `&`.
docfx now builds with 12 warnings: 3 are pre-existing CS warnings
unrelated to docs, 9 are InvalidFileLink to the cli.md file that the
Phase 3 emitter generates at build time. Strict --warningsAsErrors
validation is deferred to the end of Phase 3.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Phase 3 of the docs-site restoration plan. Adds a new top-level 'docs'
command with a 'cli' sub-command that walks the same _commands +
GetOptions() pipeline the parser uses, then writes a structured
Markdown page describing every enabled command, sub-command, language,
and option. Because it shares a data source with the parser, the page
cannot drift from the shipped binary.
Changes:
- LaunchUtils._commands gains a 'docs' entry (ConfigDocs config,
'cli' sub-command). LaunchCommandRecord is promoted from private
to internal so the emitter can iterate it. Adds an internal
EnabledCommands enumerable matching the parser's filter
(!Disabled) and ordering (by Literal, ordinal).
- ConfigDocs : ConfigRoot exposes a single --output option,
defaulting to docs/articles/cli.md.
- CliDocEmitter (shared project) renders global options, per-command
option tables, language sub-command tables, and manual sub-command
lists; writes UTF-8 (no BOM) with a trailing newline.
- Program.cs routes 'docs' to a new DoDocs handler.
- The shared project's .projitems gains CliDocEmitter.cs so any CLI
variant picks it up.
- fhir-codegen.csproj exposes internals to the new test project via
InternalsVisibleTo.
- New src/fhir-codegen.Tests project (xUnit + Shouldly, mirrors
Fhir.CodeGen.Lib.Tests style); added to fhir-codegen.sln.
- Four CliDocEmitterTests cover language coverage, command coverage
(including the sql-is-excluded invariant), TypeScript option
drift, and the UTF-8/no-BOM/trailing-newline file contract.
Default emitter output is docs/articles/cli.md (gitignored via the new
docs/.gitignore). Writing into the docs source root keeps DocFX's
filesystem-based cross-link checker happy: every '[cli](cli.md)' link
in articles/ now resolves cleanly, and 'docfx --warningsAsErrors'
exits 0 (the only warnings remaining are pre-existing CS warnings
from the metadata compile, which docfx does not promote). The earlier
docfx/cli-generated/ content root is removed from docfx.json.
All 211 tests in 'dotnet test fhir-codegen.sln --filter
"RequiresExternalRepo!=true"' pass.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…adata
Phase 4 of the docs-site restoration plan. The repo moved from
microsoft/fhir-codegen to FHIR/fhir-codegen; this scrubs the remaining
old URL references and points NuGet metadata at the new docs site.
- fhir-codegen.props: <RepositoryUrl> now points at FHIR/fhir-codegen,
and a new <PackageProjectUrl> points at the published docs site
(https://fhir.github.io/fhir-codegen/) so the 'Project URL' link on
nuget.org takes consumers to the curated landing page rather than
duplicating the source-discovery role of <RepositoryUrl>.
- README.md: replaces the stale 'Apologies - the documentation for
this project is currently quite stale… Soon(TM)' paragraph with a
real Documentation section pointing at fhir.github.io and a brief
summary of what's there.
- CHANGELOG.md: under '### CURRENT', adds the docs-site-restoration
note. The pre-existing 'Migrated from Microsoft/fhir-codegen to
FHIR/fhir-codegen.' line is left intact as it documents the
historical migration.
- ShorthandIG.cs: the embedded generation-note URL is updated from
microsoft/fhir-codegen to FHIR/fhir-codegen.
- CrossVersionResolver.cs: matching comment URL update.
Verification:
- 'grep -rn microsoft/fhir-codegen' (excluding .git, scratch, bin,
obj) returns zero hits, modulo the historical CHANGELOG migration
line which intentionally records the rename.
- 'dotnet build fhir-codegen.sln -c Release' is green.
- 'dotnet test ... --filter "RequiresExternalRepo!=true"' baseline
behaviour is unchanged: TestFirelyHashesR5(Conformance) was
already failing before this change (verified by temporarily
stashing the URL edits) and remains failing for the same
pre-existing reason; all other 210/211 tests pass.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Phase 5 of the docs-site restoration plan. Replaces the disabled,
Chocolatey-based, upload-artifact@v1 workflow with a current
GitHub Pages deploy flow:
- Triggers on push to main, pull_request to main, and
workflow_dispatch, all narrowed to docs-relevant paths.
- Uses ubuntu-latest, dotnet-install, and 'dotnet tool install -g
docfx' (no Chocolatey).
- Build job restores + builds the solution, runs the new
'fhir-codegen docs cli' emitter to write docs/articles/cli.md,
then runs 'docfx --warningsAsErrors' over the freshly populated
site source.
- Deploy job uses actions/configure-pages@v5 +
actions/upload-pages-artifact@v3 + actions/deploy-pages@v4 (the
official Pages deploy flow), gated to push events on main only.
PR runs validate the build but skip the deploy.
- Permissions are scoped to {contents: read, pages: write,
id-token: write} per the Pages-deploy contract; concurrency is
grouped by 'pages' so successive deploys serialise cleanly.
Note: emitter output goes to docs/articles/cli.md (per the Phase 3
deviation), not docfx/cli-generated/cli.md as the original plan
sketched.
Precondition (cannot be code-reviewed): the FHIR/fhir-codegen repo
must have GitHub Pages set to 'Source: GitHub Actions' under
Settings → Pages. If it is not, the deploy job's first run will
fail with a permissions error; fix is purely a settings change.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Phase 6 of the docs-site restoration plan. Adds a CI status badge to the README header that links to the new Docs workflow (.github/workflows/docs.yaml, rewritten in Phase 5). The badge will turn green on the first successful 'main' run after the docs workflow is enabled and GitHub Pages is configured to deploy from GitHub Actions. Note: Phase 6's other planned steps (smoke-testing the live site, filing follow-up issues for any link/content gaps surfaced during that smoke-test) require the deploy workflow to actually run on 'main', which is outside the scope of a pre-merge local change. Those steps are tracked as follow-ups in the plan's Progress Log. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
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
1 participant
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.
Changes for migration to FHIR Foundation.
Updates to documentation.