Skip to content

AIFACTORY-FEAT-181: Documentation template: generated sections, a stale check and a packable template for Factory repositories

Generated from the architecture model

This page is rendered from model/**/*.yaml by tools/docs_model during mkdocs build. Edit the YAML, not this page; hand-written design lives on the linked service, platform and plane pages.

A design artefact, not a tracker

This backlog is generated from model/backlog/ and validated against the architecture model. No work item exists in any tracker, and no item carries a date, an estimate or an assignee (ADR-0029).

Epic Ecosystem component extensions · Increment I1 Generate a microservice · State elaborated · Route backend-developer · Phase before development · Build order 26 of 185 (Templates and libraries)

Before development

Template or library work: every task of this feature changes a template or a shared library the Factory builds on, and it lands before the Factory's own repositories of I1 are developed. The mark travels with every task (tag phase:before-development).

Every Factory repository publishes a documentation site, and the Documentation site module of a generated product is scaffolded from the documentation template (connectsoft-documentation). The template is a MkDocs Material site with four parameters (title, description, repository URL, build definition), log4brains ADRs, the panzoom, exclude and search plugins and an Azure documentation pipeline; the template inventory records it as empty because it has no project to pack. It knows nothing of the distinction the documentation blueprint draws between generated and hand-written sections (blueprint-documentation.schema.json), has no check that a generated page is current, and no manifest or symbol catalog. The pattern this repository's own generator follows (model, generated pages written only when changed, a check that fails on a stale page, a strict build) becomes the template's. Component: Documentation template (extend).

Delivers —
Stubs —
Realizes components: cmp-documentation-template
adrs: ADR-0027, ADR-0028
Requirements —
Depends on —
Sources model/components.yaml, model/templates.yaml, docs/reference/schemas/blueprint-documentation.schema.json, ConnectSoft.DocumentationTemplate/build.md

AIFACTORY-US-305: Documentation template: a generated site marks each section as generated or hand-written, writes generated pages only on change and fails a check on a stale page

enabling · persona asset-maintainer As an asset maintainer, I want the documentation template to separate generated sections from hand-written ones and to check that generated pages are current, so that a Factory repository never publishes a generated page that no longer matches its source.

The documentation blueprint (docs/reference/schemas/blueprint-documentation.schema.json) describes a site as a template reference and a list of sections, each with an id, a title and a source that is either generated or hand-written. The documentation template scaffolds a MkDocs Material site with four parameters and knows nothing of that distinction: every page is a file somebody edits, and nothing tells a reader or a pipeline which pages a tool owns. This PBI gives the generated site the pattern this documentation repository follows for its own pages. The site carries a sections file beside mkdocs.yml that lists each section with its id, its title and its source in the two values of the blueprint. Pages of a generated section live in a folder of that section and carry a marker comment that names their generator. The generated site holds a tool folder tools/docs_site with two entry points. python -I tools/docs_site generate writes a generated page only when its content changed, so an unchanged run leaves the working tree clean. python -I tools/docs_site check regenerates in memory and fails with the list of stale pages when a committed page differs, and fails when a page without the marker sits inside a generated section, because a hand-written page there would be overwritten. A hand-written section is never touched by either command. The documentation pipeline file of the generated site (azure-pipelines-documentation.yml) does not build the site itself: it calls the shared documentation step generate/generate-microservice-documentation-steps.yaml of ConnectSoft.AzurePipelines, which installs a fixed plugin list and builds without the strict flag. The shared step therefore gains a strict switch, an input for the requirements file of the site and a hook that runs before the build; the pipeline file of the generated site switches the strict build on and passes the check command as the hook, so a failed check stops the run before the build and a build warning fails it. Consumers of the shared step that set neither keep the build of today. The site description of the template README explains the two kinds of section and the two commands.

Acceptance criteria

AC1 Given a site generated from the template, when its sections file is read, then every section has an id, a title and a source of generated or hand-written, the two values docs/reference/schemas/blueprint-documentation.schema.json defines, and the pages of a generated section carry the marker of their generator (ADR-0027: a generation input is pinned and reproducible).
AC2 Given an unchanged source, when the generate command runs twice, then the second run writes no file; given a changed source and a committed page that was not regenerated, when the check command runs, then it fails and lists the stale page (ADR-0027, NFR-14: the generated and the preserved parts of a repository stay split).
AC3 Given a page without the generator marker inside a generated section, when python -I tools/docs_site check runs, then it fails with the page named, and a page of a hand-written section is changed by neither command; the documentation pipeline of the generated site passes the check as the pre-build hook of the shared documentation step of ConnectSoft.AzurePipelines and switches its strict build on, so a failed check stops the run before the build, and a consumer of the shared step that sets neither switch builds as today (ADR-0028, NFR-14).
Traces: adrs ADR-0027, ADR-0028
Relates: nfrs NFR-14
Sources model/components.yaml, model/templates.yaml, model/template-parameters/connectsoft-documentation.yaml, docs/reference/schemas/blueprint-documentation.schema.json, docs/architecture/adr/0027-generation-input-contract.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-1333 Sections file of a generated site in the vocabulary of the documentation blueprint contract The generated site holds a sections file beside mkdocs.yml with the id, title and source of each section, the source being generated or hand-written as docs/reference/schemas/blueprint-documentation.schema.json names them, and a schema for that file ships in the template; the marker comment of a generated page is defined on the README of the generated site. ConnectSoft.DocumentationTemplate
AIFACTORY-TASK-644 Generated and hand-written sections with a stale check implementation Sections carry a source marker, generated or hand-written as the documentation blueprint names them. The generated site holds the tool folder tools/docs_site with the entry points python -I tools/docs_site generate, which writes a generated page only when its content changes, and python -I tools/docs_site check, which exits non-zero with the page named when a generated page is stale or when a page without the marker sits inside a generated section; a hand-written section is never touched by either. ConnectSoft.DocumentationTemplate
AIFACTORY-TASK-1424 Strict switch, requirements input and pre-build hook in the shared documentation step operations The shared step generate/generate-microservice-documentation-steps.yaml gains a strict parameter that adds the strict flag to the MkDocs build, a parameter for a requirements file that replaces the fixed plugin list when it is set, and a parameter for a pre-build command that runs before the build and fails the step on a non-zero exit; all three default to the behaviour of today, so existing consumers are unchanged. ConnectSoft.AzurePipelines
AIFACTORY-TASK-1334 Documentation pipeline of the generated site switches the check and the strict build on operations The documentation pipeline file azure-pipelines-documentation.yml of the generated site calls the shared documentation step of AIFACTORY-TASK-1424 with the strict switch on, the requirements file of the site and python -I tools/docs_site check as the pre-build command, and keeps the log4brains build; a failed check or a build warning fails the run before the site artifact is published. ConnectSoft.DocumentationTemplate
AIFACTORY-TASK-1335 Verify the idempotent generation, the stale page and the misplaced page verification On a generated site run python -I tools/docs_site generate twice, plant a stale generated page and a page without marker in a generated section, and run python -I tools/docs_site check; the second generation writes nothing and both planted pages fail the check by name, and the documentation pipeline of the site stops on the planted page before the build, which proves AC1 to AC3 of AIFACTORY-US-305 (ADR-0027). ConnectSoft.DocumentationTemplate

AIFACTORY-US-306: Documentation template: the API reference renders from the OpenAPI document of the repository and the ADR section from its log4brains records, so the first build is complete

enabling · persona asset-maintainer As an asset maintainer, I want the site of a service repository to render its API reference and its decisions from what the repository already holds, so that a freshly scaffolded Factory repository publishes a complete site without a hand-written page.

The documentation template carries an api folder and an adr folder with starter content, a log4brains configuration, and a documentation pipeline that builds the ADRs with log4brains and merges them into the site. Nothing connects those folders to the repository that hosts the site: the API pages are sample text and the home page is the generic one. A Factory service repository holds an OpenAPI document of its REST surface and records its decisions as log4brains records. This PBI makes two sections of the generated site generated sections in the sense of the sections file. The API reference section is produced from the OpenAPI document of the repository, one page per tag with its operations, their parameters, their responses and the scopes they require; the path of the document is a setting of the generate command, and a repository without a document, a library for example, gets no API section and no empty page. The ADR section lists the log4brains records of the repository with their status and links the pages the log4brains build produces. The home page names the site from siteTitle and siteDescription and the repository from repoUrl, and lists the sections of the sections file. With both generated sections a site scaffolded for a service builds strictly on its first run with no page written by hand. The sample API and architecture pages of the template become hand-written starter sections that a repository may delete.

Acceptance criteria

AC1 Given a generated site in a repository with an OpenAPI document, when the generate command runs, then the API reference section holds one page per tag with the operations, parameters, responses and required scopes of the document, each page carries the generator marker, and the strict build passes (ADR-0028: every service has its own repository and its own published surface; docs/reference/schemas/blueprint-documentation.schema.json names the section source).
AC2 Given a generated site in a repository without an OpenAPI document, when the generate command runs, then no API section and no empty page is produced and the navigation holds no dead entry; the ADR section lists the log4brains records of the repository with their status (ADR-0028, model/templates.yaml row of connectsoft-documentation).
AC3 Given a site scaffolded with siteTitle, siteDescription and repoUrl for a service repository, when it is built strictly for the first time, then the build passes with no hand-written page added, and the home page names the site, the repository and the sections (ADR-0027, model/template-parameters/connectsoft-documentation.yaml lists the three parameters).
Traces: adrs ADR-0027, ADR-0028
Depends on AIFACTORY-US-305
Sources model/components.yaml, model/templates.yaml, model/template-parameters/connectsoft-documentation.yaml, docs/reference/schemas/blueprint-documentation.schema.json

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-1336 API reference generator over the OpenAPI document of the repository implementation The generate command of the generated site reads the OpenAPI document at the configured path and writes one page per tag with operations, parameters, responses and required scopes into the API reference section; without a document it writes no section and removes the navigation entry. ConnectSoft.DocumentationTemplate
AIFACTORY-TASK-645 API reference and ADR sections from the repository documentation The API reference section renders from the OpenAPI document of the repository and the ADR section from the log4brains records the template already carries, so a Factory service repository scaffolds a site that is complete on the first build without a hand-written page; the home page names the service from the template parameters; the sample API and architecture pages are marked as hand-written starter sections. ConnectSoft.DocumentationTemplate
AIFACTORY-TASK-1337 Verify the first strict build with and without an OpenAPI document verification Scaffold one site into a fixture repository with an OpenAPI document and log4brains records and one into a repository without a document, generate and build both strictly; the first holds the API pages per tag, the second holds no API section, which proves AC1 to AC3 of AIFACTORY-US-306. ConnectSoft.DocumentationTemplate

AIFACTORY-US-307: Documentation template: the repository gains a pack project, a generated site carries .connectsoft/template-manifest.json and the package exports its symbol catalog

enabling · persona asset-maintainer As an asset maintainer, I want the documentation template to pack like the other templates and to record how a site was generated, so that the inventory lists it as a shipping template and a recipe can pin it by id and version.

The template inventory of this repository records the documentation template as empty with the reason that it has no project file: the repository holds a nuspec, a solution file and the template configuration, but no project to pack. The internal guide of the template (build.md of the template) tells a maintainer to run dotnet pack and to update the version in a project file that does not exist, and draws a Docs folder where the repository has docs. A site generated from the template keeps no record of the template, its version or the values of siteTitle, siteDescription, repoUrl and buildDefinitionNumber. This PBI makes the template a packable one and gives it the manifest and the catalog under the file names the library template feature of this epic sets, without inventing others. The repository gains a pack project beside the nuspec so that the inventory finds a project and the package is produced by one command. A generated site carries .connectsoft/template-manifest.json with the template id connectsoft-documentation, the version of the template package and the value of every parameter; it is preserved, and a regeneration reads it as its input. The package carries .template.config/template-manifest.schema.json and .template.config/symbol-catalog.json, the catalog produced from the template configuration at pack time with every symbol, its type, default and description. The shapes of the manifest and of the catalog are those of the library template; the template adopts them and defines no variant. The internal guide is corrected to the commands and folders that exist.

Acceptance criteria

AC1 Given the template repository with its pack project, when the template inventory of this repository runs, then the row of connectsoft-documentation in model/templates.yaml records a project and no longer the status empty, and the packed package installs with dotnet new install (ADR-0028 amendment on scaffolding from published templates).
AC2 Given a site generated from the installed package, when its repository is inspected, then .connectsoft/template-manifest.json holds the template id connectsoft-documentation, the version of the package and the values of siteTitle, siteDescription, repoUrl and buildDefinitionNumber, validates against .template.config/template-manifest.schema.json of the package and is read as the input of a regeneration (ADR-0027 decision 2 pins a generation input by id, version and hash).
AC3 Given the packed template, when the package is inspected, then .template.config/symbol-catalog.json lists every symbol of the template configuration with its type, default and description and equals the symbols of model/template-parameters/connectsoft-documentation.yaml after the next inventory; the file names and shapes are those the library template sets (ADR-0027, ADR-0028).
Traces: adrs ADR-0027, ADR-0028
Depends on feature:component-library-template-factory-profile
Sources model/components.yaml, model/templates.yaml, model/template-parameters/connectsoft-documentation.yaml, model/backlog/pbis/component-extensions/component-library-template-factory-profile.yaml, docs/architecture/adr/0027-generation-input-contract.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-646 A packable template with a manifest and symbol catalog contract The template gains the pack project the inventory misses, packs and installs like the other templates, and its package carries the manifest schema .template.config/template-manifest.schema.json and the symbol catalog .template.config/symbol-catalog.json in the shapes the library template defines; the manifest of a generated site is the file .connectsoft/template-manifest.json. ConnectSoft.DocumentationTemplate
AIFACTORY-TASK-1338 Manifest written at generation and catalog produced at pack time implementation The template writes .connectsoft/template-manifest.json into a generated site with the template id, the package version and the value of every parameter and preserves it on regeneration; a pack step reads the template configuration and writes .template.config/symbol-catalog.json into the package. ConnectSoft.DocumentationTemplate
AIFACTORY-TASK-1339 Internal guide of the template corrected to the commands and folders that exist documentation The internal guide build.md of the template names the pack project, the real folder docs, the pack and install commands that work and the manifest and catalog files, and no longer refers to a project file or a folder the repository does not hold. ConnectSoft.DocumentationTemplate
AIFACTORY-TASK-1340 Template inventory of the documentation repository re-run for the packable template documentation After python -I tools/docs_model inventory-templates the row of connectsoft-documentation in model/templates.yaml records its project and the status shipping, model/template-parameters/connectsoft-documentation.yaml lists the symbols of the catalog, and docs/architecture/catalogs/templates.md renders the row. ConnectSoft.AI.SoftwareFactory.Documentation
AIFACTORY-TASK-1341 Verify the pack, the manifest read-back and the symbol catalog verification Pack and install the template, generate a site, read the manifest back and compare it with the parameters passed, and compare the catalog of the package with model/template-parameters/connectsoft-documentation.yaml; the three comparisons pass and prove AC1 to AC3 of AIFACTORY-US-307. ConnectSoft.DocumentationTemplate

AIFACTORY-US-308: Documentation template: the packed template is installed, instantiated, checked and built strictly before the package publishes to the ConnectSoft feed

evidence · persona asset-maintainer As an asset maintainer, I want every change of the documentation template to be gated by the site it generates from the packed candidate, so that a package that would scaffold a site that does not build never reaches the feed.

This PBI is the gate of the feature. The installer pipeline of the template (azure-pipelines-template.yml of the template) packs the nuspec and pushes the installer package; it neither installs the packed candidate nor generates a site from it, and the internal guide of the template lists a template testing pipeline as a future improvement. The gate turns the local test of that guide into cases of the installer pipeline, which calls the shared installer job of ConnectSoft.AzurePipelines in place of its own pack and push steps and switches on the gate hook and the version guard that AIFACTORY-TASK-1426 of the feature component-base-template-findings delivers. The candidate is packed once and installed, and the hook runs the cases against it after the pack and before the push. A site is instantiated with the four parameters siteTitle, siteDescription, repoUrl and buildDefinitionNumber into a fixture repository that holds an OpenAPI document and log4brains records, and a second site into a repository without a document. For each site the Python requirements are installed, the generate command and the check command run, the site is built strictly, the ADRs are built with log4brains, the manifest is read back and the output is scanned for template placeholders that were not replaced. A site that fails any stage fails the run with the case and the stage named, and the push is not reached. A fixture with a planted stale page proves that the check stops the run. Publication follows both cases and pushes the package to the ConnectSoft feed with a version that is not yet on the feed, and the version guard, which the template switches on, refuses a repeated version. This is an evidence PBI: a template feature has no scenario, so the gate names what it proves through traces.adrs and its sources.

Acceptance criteria

AC1 Given a change of the template, when its installer pipeline runs, then the candidate is packed once and installed, the gate hook of the shared installer steps (AIFACTORY-TASK-1426) runs the two cases, a site is instantiated with the four parameters into a repository with an OpenAPI document and into one without, and each site is generated, checked, built strictly, built with log4brains, compared with its manifest and scanned for placeholders (ADR-0028 amendment on scaffolding from published templates; model/template-parameters/connectsoft-documentation.yaml lists the four parameters).
AC2 Given a site fails any stage, when the pipeline evaluates the run, then the gate hook fails the run with the case and the stage named and the push is not reached; a fixture with a planted stale generated page proves that the check stops the run before the build (ADR-0027, model/backlog/epics.yaml states the gate as the completion of the epic).
AC3 Given both cases are green, when the push step runs, then the package is pushed to the ConnectSoft feed with a version that is not on the feed and the version guard of the shared installer steps, which the template switches on, refuses a repeated version with the reason (ADR-0028, docs/architecture/catalogs/templates.md keeps the row of the template).
Traces: adrs ADR-0027, ADR-0028
Depends on AIFACTORY-US-305, AIFACTORY-US-306, AIFACTORY-US-307, feature:component-base-template-findings
Sources model/components.yaml, model/backlog/epics.yaml, model/template-parameters/connectsoft-documentation.yaml, docs/architecture/catalogs/templates.md, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-1342 Installer pipeline instantiates the packed candidate and builds the generated sites operations The installer pipeline file of the template calls the shared installer job of ConnectSoft.AzurePipelines in place of its own pack and push steps, so the candidate is packed once and installed, and switches on the gate hook and the version guard of AIFACTORY-TASK-1426; the command it passes to the hook instantiates the two site cases, installs the Python requirements, runs the generate and check commands, the strict build and the log4brains build, reads the manifest back and scans for placeholders; the push follows only when both cases passed, and the guard refuses a version that is already on the feed. ConnectSoft.DocumentationTemplate
AIFACTORY-TASK-1343 Fixture repositories and a planted stale page for the gate fixture The template repository holds a fixture with an OpenAPI document and log4brains records, a fixture without a document, and a planted case whose generated page is stale; the planted case asserts that the run fails at the check stage with the page named and that publication is not reached. ConnectSoft.DocumentationTemplate
AIFACTORY-TASK-1344 Verify the gate on a green run and on the planted run verification One pipeline run with both site cases green reaches publication and one run with the planted stale page fails before it; both runs prove AC1 to AC3 of AIFACTORY-US-308 (ADR-0027, ADR-0028). ConnectSoft.DocumentationTemplate

AIFACTORY-US-120: Documentation template: generated sections, a stale check and a packable template for Factory repositories is delivered and proven on a generated solution

enabling · persona asset-maintainer As an asset maintainer, I want Documentation template to carry generated sections, a stale check and a packable template for Factory repositories, so that it serves documentation sites of Factory repositories; the Documentation site module of generated products without later rework.

This is the integration PBI of the feature. An asset maintainer packs the documentation template with the sections file, the generate and check commands, the API reference and ADR sections, the manifest and the symbol catalog, installs the package and instantiates it in the installer pipeline. Each generated site passes its check and its strict build before the package is allowed to publish; a stale page or a build warning fails the run and blocks publication. The implementation lives in the earlier PBIs of this file; this PBI proves them together on the site a Factory service repository gets. From the published package a site is generated into a fixture repository in the shape of a Factory service, with an OpenAPI document and decision records. Its first strict build is complete with no page written by hand, its manifest names the template, the version and the parameter values, and its documentation pipeline stops on a planted stale page. The feature is done when that site builds from a fresh install of the published package. Repository of the feature: ConnectSoft.DocumentationTemplate. The Documentation site module of a generated product is scaffolded from the same package in a later increment.

Acceptance criteria

AC1 Given the template repository ConnectSoft.DocumentationTemplate with the work of this feature, when the template is packed, installed and instantiated in its pipeline, then each generated site passes its check and its strict build before the package publishes with a verified version (ADR-0028, model/components.yaml).
AC2 Given the work of AIFACTORY-TASK-644 (generated and hand-written sections with a stale check) is done, then sections carry a source of generated or hand-written as docs/reference/schemas/blueprint-documentation.schema.json names them, generated pages are written only when their content changes, a check command fails on a stale page and on a hand-written page inside a generated section, and the documentation pipeline runs the check and the strict build (ADR-0027).
AC3 Given the work of AIFACTORY-TASK-645 (API reference and ADR sections from the repository) is done, then the API reference section renders from the OpenAPI document of the repository and the ADR section from its log4brains records, so a Factory service repository scaffolds a site that is complete on the first build without a hand-written page (ADR-0028, model/templates.yaml).
AC4 Given the work of AIFACTORY-TASK-646 (a packable template with a manifest and symbol catalog) is done, then the template has the pack project the inventory misses, a generated site carries .connectsoft/template-manifest.json with the template id and version, the package carries .template.config/symbol-catalog.json, and the pipeline instantiates the packed template, builds the site strictly and publishes the package to the ConnectSoft feed with a verified version (ADR-0027, model/template-parameters/connectsoft-documentation.yaml).
Traces: adrs ADR-0027, ADR-0028
Depends on AIFACTORY-US-305, AIFACTORY-US-306, AIFACTORY-US-307, AIFACTORY-US-308
Sources model/components.yaml, model/templates.yaml, model/template-parameters/connectsoft-documentation.yaml, docs/reference/schemas/blueprint-documentation.schema.json

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-1345 Generate the site of a Factory service repository shape from the published package verification A probe installs the published template package, generates a site into a fixture repository in the shape of a Factory service, runs the generate and check commands and the strict build, and plants a stale page that the documentation pipeline of the site refuses; the run proves AC2 to AC4 of AIFACTORY-US-120 on the published package (ADR-0027, ADR-0028). ConnectSoft.DocumentationTemplate
AIFACTORY-TASK-679 Verify documentation-template-factory-docs-delivered by running the declared command verification Run DISABLE_MKDOCS_2_WARNING=true python -m mkdocs build --strict on the template site and on every generated site of the gate after the published package is installed; it passes and proves AC1 to AC4 of AIFACTORY-US-120. ConnectSoft.DocumentationTemplate