Skip to content

Auto-generate and publish API documentation #460

Description

@7sharp9

Follow-up to #234, item 4 ("Automatically update and add api documentation").
Deferred out of #234's scope by
ADR-0021
(decision 4).

Problem

There is no generated API reference for the ~20 Informedica.*.Lib projects. The
XML documentation comments the F# coding standard requires
(.github/instructions/fsharp-coding.instructions.md) are written but never
rendered anywhere — the only navigable documentation is hand-written prose under
docs/domain/ and docs/mdr/, which describes the domain model rather than the
public API surface.

Scope to decide

  • Tool: fsdocs (F#-native,
    understands F# signatures and can also render the existing Scripts/*.fsx as
    literate docs) vs docfx (broader .NET tooling, weaker F# rendering). fsdocs is
    the obvious starting candidate for an all-F# solution.
  • Which projects: all 20+ libraries is a lot of surface area, much of it
    internal. Starting with the libraries that have a genuinely public contract
    (GenUNITS, GenSOLVER, GenCORE, GenFORM, GenORDER,
    GenPRES.Shared) may be more useful than everything at once.
  • Hosting: GitHub Pages from master vs published per release. None of this
    infrastructure exists yet — there is no gh-pages branch and no Pages config.
  • Trigger: on every merge to master, or only when a release lands (which
    would pair with Publish the Docker image automatically on release #459 and reuse release.yml's "a release happened" signal).
  • Enforcement: whether missing/malformed XML docs should warn or fail the
    build. Turning this on repo-wide would be noisy immediately; scoping it to
    newly-touched files is the gentler option.
  • Prerequisite: GenerateDocumentationFile is not currently set in
    Directory.Build.props, so no XML doc files are emitted at all today. That has
    to be turned on first (and will surface a wave of FS3390/missing-doc warnings).

MDR note

Generated API documentation is process/reference material, not clinical logic. It
does not replace anything in docs/mdr/ and should not be treated as a Design
History File input — the hand-written domain and design-history documents remain
authoritative.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

buildIssues with the build system, CI, or compilationdocumentationImprovements or additions to documentationtoolingDeveloper tooling, scripts, or project infrastructure

Type

No type

Projects

No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions