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 |