diff --git a/partY-diagrams-admin.adoc b/partY-diagrams-admin.adoc new file mode 100644 index 0000000..d742c4f --- /dev/null +++ b/partY-diagrams-admin.adoc @@ -0,0 +1,377 @@ += Diagram Generation — Administrator / Developer Configuration Reference +:toc: left +:toclevels: 3 +:sectnums: + +This document covers all configuration options for the diagram generation tool (`oas-diagrams`). It is intended for administrators and developers who need to customize how diagrams are produced — complexity thresholds, inheritance handling, discriminator rendering, legend layout, and more. + +For an overview of diagram structure, simple types, and the user-facing Diagram Subset Control feature, see the link:partY-diagrams-user.adoc[End-User Guide]. + +== How Configuration Works + +Configuration is layered: + +. *Fallback baseline* — minimal structural defaults (`config/fallback.yaml`) +. *Embedded defaults* — domain-specific overrides merged on top (`config/defaults.yaml`) +. *User config files* — one or more YAML/JSON files passed via `--config` (last wins) + +== Simple Types + +Simple types are treated as leaf nodes in diagrams — they are rendered inline and never broken out into separate sub-resource diagrams. + +=== `simpleTypes` + +An explicit list of type names to treat as simple/leaf: + +[source,yaml] +---- +simpleTypes: + - TimePeriod + - Money + - Quantity + - Duration + - Tax + - Value + - Any + - object + - Number + - Date +---- + +These types will appear as property type annotations but won't get their own boxes or breakout diagrams. + +=== `simpleEndings` + +Type name suffixes that mark a type as simple: + +[source,yaml] +---- +simpleEndings: + - Type + - Error +---- + +Any schema ending in `Type` or `Error` (e.g., `StatusType`, `ValidationError`) is treated as a leaf node. + +=== `nonSimpleEndings` + +Exceptions to `simpleEndings` — suffixes that should *not* be treated as simple even if they match: + +[source,yaml] +---- +nonSimpleEndings: + - RefType + - TypeRef + - RoleType +---- + +So `PartyRoleType` would remain a full node despite ending in `Type`, because it ends in `RoleType`. + +== Complexity and Breakout Control + +This section controls how the tool decides which sub-resources to break out into separate diagrams. + +=== `subResourceConfig` + +Explicitly defines which sub-resources should be broken out for a given resource, bypassing automatic complexity analysis: + +[source,yaml] +---- +subResourceConfig: + Service: + - Feature + - Characteristic + - Intent + - IntentExpression + - PlaceRefOrValue + - EntityRefOrValue +---- + +When a resource has an entry here, the listed types are forced as breakouts regardless of the complexity analysis results. This gives precise control over diagram structure for resources where the automatic analysis doesn't produce the desired layout. + +=== Strategy Selection + +[source,yaml] +---- +complexity: + strategy: path-complexity # or "graph-analysis" (default) +---- + +* *`graph-analysis`* — Uses node count, edge count, and fan-out heuristics to identify breakout candidates. +* *`path-complexity`* — Computes path-based complexity scores per node; candidates with highest complexity are broken out until the total falls below threshold. + +You can also pass `--breakout-strategy path-complexity` on the CLI. + +=== Key Thresholds + +[source,yaml] +---- +complexity: + enabled: true + breakoutSubgraphNodes: 12 # Min nodes a subgraph must have to be a breakout candidate + breakoutFanout: 8 # Min fan-out (outbound edges) to trigger breakout + minBreakoutNodes: 3 # A breakout diagram must have at least this many nodes + breakoutMaxDepth: 2 # Max depth levels for automatic breakout discovery + maxNodes: 25 # Target max nodes per diagram + maxEdges: 40 # Target max edges per diagram + excludeEnumsAndRefs: true # Exclude enums and ref-types from complexity counts +---- + +=== Path-Complexity Strategy Additional Settings + +[source,yaml] +---- +complexity: + maxComplexity: 2000 # Total complexity budget; candidates subtracted until below this + minNodeComplexity: 100 # Minimum complexity score for a node to be a breakout candidate + maxDiscriminatorMembers: 4 # Discriminators with more members than this are breakout candidates +---- + +=== Wrapper Suppression + +[source,yaml] +---- +complexity: + suppressTrivialWrapperBreakouts: true +---- + +Prevents breakouts for "wrapper" types whose diagrams would be trivial (all non-Ref children are themselves already broken out). Default: `true`. + +== Inheritance and Schema Handling + +=== `coreInheritanceTypes` + +Types to treat as abstract base classes that get flattened into inheriting types rather than rendered as separate nodes: + +[source,yaml] +---- +coreInheritanceTypes: + - Entity + - Entity_FVO + - Entity_MVO + - Extensible + - Addressable + - Reference +---- + +=== `coreInheritanceRegexp` + +Regex patterns for additional inheritance type matching: + +[source,yaml] +---- +coreInheritanceRegexp: + - "^Gc.*" +---- + +=== `subClassExcludeRegexp` + +Regex patterns for schema names to exclude entirely from diagram rendering (e.g., create/update variants): + +[source,yaml] +---- +subClassExcludeRegexp: + - ".*_Create$" + - ".*_Update$" + - ".*_FVO$" + - ".*_MVO$" +---- + +=== `includeInherited` + +Whether to show inherited properties in sub-types: + +[source,yaml] +---- +includeInherited: true +---- + +=== `expandPropertiesFromAllOfs` + +Whether to inline properties from `allOf` base types into the referencing type: + +[source,yaml] +---- +expandPropertiesFromAllOfs: false +---- + +== Discriminator (Polymorphism) Settings + +=== `includeDiscriminatorMapping` + +Show the discriminator mapping values in diagrams: + +[source,yaml] +---- +includeDiscriminatorMapping: true +---- + +=== `includeDiscriminatorEdge` + +Draw edges from discriminator nodes to their subtypes: + +[source,yaml] +---- +includeDiscriminatorEdge: true +---- + +=== `minDiscriminators` + +Minimum number of discriminator subtypes before rendering a full discriminator node (below this, subtypes are shown inline): + +[source,yaml] +---- +minDiscriminators: 4 +---- + +=== `discriminatorSpreadThreshold` + +When a discriminator has more subtypes than this, the layout "spreads" them to prevent overcrowding: + +[source,yaml] +---- +discriminatorSpreadThreshold: 5 +---- + +== Enumeration Display + +=== `truncateLargeEnums` + +Truncate long enum value lists in diagrams to keep boxes manageable: + +[source,yaml] +---- +truncateLargeEnums: true +truncateEnumsTrigger: 15 # Truncate if more than this many values +truncateEnumsCount: 10 # Show this many values before the "truncated" message +---- + +=== `includeOrphanEnums` + +Include enum types that aren't directly referenced by any resource property: + +[source,yaml] +---- +includeOrphanEnums: true +---- + +=== `orphanEnumsByResource` + +Assign specific orphan enums to specific resources: + +[source,yaml] +---- +orphanEnumsByResource: + TroubleTicket: + - TroubleTicketStatusType + - TroubleTicketPriorityType +---- + +== Properties Display + +=== `includeMetaProperties` + +Include meta/framework properties (like `@type`, `@baseType`, `@schemaLocation`): + +[source,yaml] +---- +includeMetaProperties: true +---- + +=== `onlyMandatoryForPost` + +For POST-style operations, only show mandatory properties: + +[source,yaml] +---- +onlyMandatoryForPost: true +---- + +=== `showSubResourceProperties` + +Show properties inside sub-resource (breakout-reference) nodes: + +[source,yaml] +---- +showSubResourceProperties: true +---- + +== Legend Configuration + +Control the legend box that appears in generated diagrams: + +[source,yaml] +---- +legend: + includeLegend: true + mandatoryPropertyNote: " (1) : Mandatory property" + legendSequence: + - "<>" + - "<>" + - "<>" + - "<>" + - "<>" + - "<>" + legendEntries: + "<>": + color: "#E6F5F7" + text: "Enumeration" + "<>": + color: "#FFFFFFF" + text: "Resource (entry point)" + "<>": + color: "#FFFFE0" + text: "Sub-resource (reference entity)" + "<>": + color: "#FCF2E3" + text: "Sub-resource" + "<>": + color: "#FADADD" + text: "Sub-resource with details in separate diagram" + "<>": + color: "#F2F3F5" + text: "Discriminator (oneOf) node" +---- + +== Type Mapping + +Control how OAS primitive types and formats map to display names in diagrams: + +[source,yaml] +---- +typeMapping: + integer: Integer + string: String + boolean: Boolean + number: Number + +formatToType: + date-time: DateTime + date: Date + float: Float + uri: Uri + int32: Integer32 + int64: Integer64 + uuid: UUID +---- + +== Path Filtering + +=== `ignorePaths` + +Path segments to ignore during resource discovery: + +[source,yaml] +---- +ignorePaths: + - "/listener/" +---- + +=== `filterEventsFromDiscovery` + +Exclude event-related paths from automatic resource discovery: + +[source,yaml] +---- +filterEventsFromDiscovery: true +---- diff --git a/partY-diagrams-user.adoc b/partY-diagrams-user.adoc new file mode 100644 index 0000000..42d6094 --- /dev/null +++ b/partY-diagrams-user.adoc @@ -0,0 +1,171 @@ += Diagram Generation — End-User Guide +:toc: left +:toclevels: 3 +:sectnums: + +This guide covers the user-facing aspects of diagram generation: understanding how diagrams are structured, what simple types mean, and how to control which diagrams appear in the generated user guide. + +For the full configuration reference (complexity thresholds, inheritance handling, legend customization, etc.), see the link:partY-diagrams-admin.adoc[Administrator / Developer Configuration Reference]. + +== Understanding Diagram Structure + +The diagram generator reads an OpenAPI specification and produces PlantUML diagrams for each resource. Each resource gets: + +* A *pivot diagram* — the main resource diagram showing the top-level structure +* Zero or more *sub-resource breakout diagrams* — separate diagrams for complex sub-resources that would make the main diagram too crowded + +The tool automatically decides which sub-resources to break out based on complexity analysis. You can override these decisions using the Diagram Subset Control settings described below. + +== Simple Types + +Simple types are treated as leaf nodes in diagrams — they appear as property type annotations but never get their own boxes or breakout diagrams. This keeps diagrams focused on the meaningful structure. + +Types are considered simple if they: + +* Are explicitly listed (e.g., `TimePeriod`, `Money`, `Quantity`, `Duration`) +* Have names ending in certain suffixes (e.g., `StatusType`, `ValidationError`) +* With exceptions for suffixes like `RefType`, `TypeRef`, `RoleType` which remain full nodes + +You don't normally need to change these defaults, but they can be configured — see the link:partY-diagrams-admin.adoc[admin guide] for details. + +[[subset-control]] +== Diagram Subset Control + +=== Overview + +When generating user guides for APIs with many resources and deep sub-resource hierarchies, the output can contain an overwhelming number of diagrams. The **Diagram Subset Control** feature lets you choose exactly which sub-resource breakout diagrams appear in the generated user guide, on a per-resource or global basis. + +The main (pivot) diagram for each resource is always included — filtering only applies to sub-resource breakout diagrams. + +==== Background: What Are Sub-Resource Diagrams? + +The diagram generator uses complexity analysis to automatically "break out" complex sub-resources into their own separate diagrams. These breakouts are types like `Characteristic`, `ContactMedium`, `Feature`, `PlaceRefOrValue`, `GeographicAddress`, `Intent`, etc. — types with enough internal structure to warrant their own diagram. + +Simple types (like `TimePeriod`, `Money`, `Quantity`, `Duration`) and types matching `simpleEndings` patterns (like `*Type`, `*Error`) are already rendered inline as leaf nodes by the diagram generator and never produce breakout diagrams. This feature controls which of the *breakout* diagrams appear in the user guide. + +You can see which sub-resources were broken out for each resource by inspecting the `breakoutSequence` section in the generated `diagrams.yaml`. + +=== Configuration Keys + +Add these to your project YAML config file (passed via `--config` / `-c`): + +[options=header] +|=== +| Key | Type | Description | +| `diagramSubsets` | `map` | Whitelist: include only these sub-resource diagrams | +| `diagramExclusions` | `map` | Blacklist: exclude these sub-resource diagrams | +| `globalDiagramExclusions` | `string[]` | Exclude these sub-resource types from all resources | +|=== + +When none of these keys are set, all diagrams are included (existing default behavior). + +=== Usage Examples + +The examples below use sub-resource names as they appear in `diagrams.yaml` — these are the complex types that the diagram generator broke out into separate diagrams. + +==== Include only specific sub-resource diagrams (whitelist) + +For a resource like `CheckServiceQualification` that might have 15+ breakout diagrams, you can restrict to just the most important ones: + +```yaml +diagramSubsets: + CheckServiceQualification: + - CheckServiceQualificationItem + - Service + - PlaceRefOrValue +``` + +Result: The `CheckServiceQualification` resource will show only its pivot diagram plus diagrams for `CheckServiceQualificationItem`, `Service`, and `PlaceRefOrValue`. All other breakout diagrams (like `GeographicAddress`, `GeographicLocation`, `ContactMedium`, `Intent`, etc.) are excluded. + +==== Exclude a few noisy diagrams (blacklist) + +When most breakout diagrams for a resource are useful but a few add clutter: + +```yaml +diagramExclusions: + Individual: + - TaxExemptionCertificate + - PartyOrPartyRole +``` + +Result: `Individual` will include its pivot plus `Party`, `Characteristic`, and `ContactMedium` diagrams, but *not* `TaxExemptionCertificate` or `PartyOrPartyRole`. + +==== Exclude common types globally + +Some sub-resource types appear across many resources but add little value as separate diagrams: + +```yaml +globalDiagramExclusions: + - ContactMedium + - Characteristic +``` + +Result: `ContactMedium` and `Characteristic` sub-resource diagrams are excluded from every resource in the user guide. These are common breakout types that often have a similar structure across resources and may not warrant individual diagrams for every resource. + +==== Combining all three + +```yaml +diagramSubsets: + CheckServiceQualification: + - CheckServiceQualificationItem + - Service + - PlaceRefOrValue + - Characteristic + +diagramExclusions: + QueryServiceQualification: + - IntentExpression + - GeographicLocationRefOrValue + +globalDiagramExclusions: + - ContactMedium + - Characteristic +``` + +- **CheckServiceQualification** uses the whitelist — only `CheckServiceQualificationItem`, `Service`, `PlaceRefOrValue`, and `Characteristic` appear. Note that `Characteristic` is included here even though it's in `globalDiagramExclusions`, because `diagramSubsets` is authoritative and overrides global exclusions. +- **QueryServiceQualification** excludes `IntentExpression`, `GeographicLocationRefOrValue`, `ContactMedium`, and `Characteristic` (resource + global exclusions combine additively). +- **All other resources** exclude `ContactMedium` and `Characteristic` globally. + +=== Precedence Rules + +1. **`diagramSubsets` wins** — If a resource has a `diagramSubsets` entry, that list is the only filter applied. Both `diagramExclusions` and `globalDiagramExclusions` are ignored for that resource. +2. **Resource-specific inclusion overrides global exclusion** — If `diagramSubsets` for a resource includes a type that's in `globalDiagramExclusions`, the diagram is still included. +3. **Resource + global exclusions combine** — When no `diagramSubsets` entry exists for a resource, `diagramExclusions` and `globalDiagramExclusions` are merged additively. +4. **Pivot diagram is always included** — The main resource diagram is never filtered out, regardless of configuration. + +=== Cross-Reference Behavior + +When a sub-resource diagram is excluded: +- No anchor or cross-reference link is generated pointing to it. +- If the same sub-resource type is included for a *different* resource, cross-references will point there instead. +- If a sub-resource type is excluded from *all* resources, any cross-reference links to it are omitted entirely (no broken links). + +=== Logging + +When diagrams are filtered, the generator logs which sub-resources were excluded: + +``` +Diagram filter (diagramSubsets): CheckServiceQualification — excluded 12 sub-resource diagram(s): GeographicAddress, GeographicLocation, ContactMedium, ... +``` + +This helps verify your configuration is working as intended. + +=== Relationship to Diagram Generation Config + +This feature operates at the **user guide generation** level, not at diagram generation. The diagram generator has its own controls that determine which types become breakout diagrams in the first place: + +- **`simpleTypes`** — Types like `TimePeriod`, `Money`, `Quantity` that are always rendered inline (never breakouts). +- **`simpleEndings`** — Suffixes like `Type`, `Error` that mark types as simple (except `nonSimpleEndings` like `RefType`). +- **`subResourceConfig`** — Explicit breakout lists per resource used by the diagram generator (e.g., `Service: [Feature, Characteristic, Intent, ...]`). +- **`complexity`** settings — Control automatic breakout thresholds (`breakoutSubgraphNodes`, `breakoutFanout`, `minBreakoutNodes`). + +The diagram subset control feature complements these settings. The diagram generator decides *what* breakout diagrams exist; the user guide generator with diagram subset control decides *which* of those appear in the final document. + +=== Tips + +- Check `diagrams.yaml` to see which sub-resources are actually available for a resource before configuring filters. +- Use `diagramSubsets` when you want tight control over exactly which breakout diagrams appear for a resource. +- Use `diagramExclusions` when most diagrams are useful but a few are noisy. +- Use `globalDiagramExclusions` for common breakout types that clutter the user guide across many resources (e.g., `ContactMedium`, `Characteristic` when they have similar structures everywhere). +- An empty `diagramSubsets` list (e.g., `CheckServiceQualification: []`) means "show only the pivot diagram" — useful for resources where only the top-level structure matters. +- Non-existent resource or sub-resource names in the config are silently ignored, so config files can be shared across multiple API projects. diff --git a/partY-userguide-admin.adoc b/partY-userguide-admin.adoc new file mode 100644 index 0000000..26ec2e9 --- /dev/null +++ b/partY-userguide-admin.adoc @@ -0,0 +1,292 @@ += User Guide Generation — Administrator / Developer Configuration Reference + +This document covers all configuration options for the user guide generator. It is intended for administrators and developers who need to customize generation behavior. + +For an overview of what the tool produces and how to interpret its output, see the link:partY-userguide-user.adoc[End-User Guide]. + +== Configuration + +The tool ships with defaults in `config/defaults.yaml`. Override settings by passing one or more `--config` files. + +=== Resource Filtering + +[cols="2,1,2,4"] +|=== +| Setting | Type | Default | Description + +| `excludedResources` +| `string[]` +| `[EventSubscription, Hub]` +| Resources to omit entirely from the user guide + +| `resourceMapping` +| `map` +| `{EventSubscription: Hub}` +| Maps OAS schema names to API resource names +|=== + +Config file key: `userguide::excludedResources` (replaces), `resourceMapping` (shallow merge) + +=== Display Format + +[cols="2,1,2,4"] +|=== +| Setting | Type | Default | Description + +| `imageFormat` +| `string` +| `svg` +| Default diagram image format (`svg`, `png`, `puml`) + +| `typeMapping` +| `map` +| `{integer: Integer, string: String, ...}` +| Maps OAS base types to display names + +| `formatToType` +| `map` +| `{date-time: DateTime, date: Date, ...}` +| Maps OAS format values to display names + +| `truncateEnumsTrigger` +| `number` +| `50` +| Truncate enum lists when more values than this + +| `truncateEnumsCount` +| `number` +| `40` +| Number of enum values shown before truncation + +| `includeMetaProperties` +| `boolean` +| `true` +| Include `@type`, `@baseType`, `@schemaLocation` in property tables + +| `insertSoftBreakHints` +| `boolean` +| `true` +| Insert zero-width spaces for better text wrapping in table columns +|=== + +=== Soft Break Hints + +Fine-grained control over where soft break markers are inserted in generated prose: + +[cols="2,1,2,4"] +|=== +| Setting | Type | Default | Description + +| `softBreakHints.marker` +| `string` +| `"\u200B"` (zero-width space) +| Character inserted at break points + +| `softBreakHints.separatorChars` +| `string` +| `"/_\\-."` +| Characters after which a break marker is inserted + +| `softBreakHints.splitCamelCase` +| `boolean` +| `true` +| Insert marker at camelCase boundaries (e.g., `productOrder`) + +| `softBreakHints.splitAlphaNumeric` +| `boolean` +| `true` +| Insert marker at alpha-numeric boundaries (e.g., `Type2`) +|=== + +=== Simple Types (Sub-Resource Filtering) + +Types matching these patterns are shown inline in property tables but never rendered as sub-resource sections: + +[cols="2,1,2,4"] +|=== +| Setting | Type | Default | Description + +| `simpleTypes` +| `string[]` +| `[TimePeriod, Money, Quantity, Duration, ...]` +| Explicit type names treated as simple + +| `simpleEndings` +| `string[]` +| `[Type, Error]` +| Suffixes that mark types as simple + +| `nonSimpleEndings` +| `string[]` +| `[RefType, TypeRef, RoleType]` +| Exceptions to `simpleEndings` +|=== + +=== Operations and Rules Integration + +[cols="2,1,2,4"] +|=== +| Setting | Type | Default | Description + +| `operationsOrder` +| `string[]` +| `[GET, POST, PATCH, PUT, DELETE]` +| Order of operations in the document + +| `includeAllPatchableFromRules` +| `boolean` +| `true` +| Include all patchable attributes from rules, even if not in OAS PATCH schema + +| `rulesSamplesBeforeAPI` +| `boolean` +| `true` +| Prefer sample values from rules file over OAS samples + +| `useResourceSampleFallback` +| `boolean` +| `true` +| Use convention-based file lookup for resource sample files +|=== + +=== Cross-References + +[cols="2,1,2,4"] +|=== +| Setting | Type | Default | Description + +| `useResourceCrossReferences` +| `boolean` +| `true` +| Generate `<>` cross-references for sub-resource types + +| `useDiagramCrossReferences` +| `boolean` +| `true` +| Generate cross-references to diagram sections +|=== + +=== Meta Properties and Non-Patchable + +[cols="2,1,2,4"] +|=== +| Setting | Type | Default | Description + +| `metaProperties` +| `string[]` +| `[@type, @baseType, @schemaLocation]` +| Properties given special "meta" treatment + +| `nonPatchable` +| `map` +| `{@type: ..., @baseType: ..., @schemaLocation: ...}` +| Attributes always shown as non-patchable with annotation text + +| `specialNonPatchable` +| `boolean` +| `true` +| Apply special annotation logic for inherited immutable properties +|=== + +Config file key: `userguide::metaProperties` (replaces) + +=== Diagram Subset Control + +Control which breakout diagrams appear per resource. See the dedicated link:partY-diagrams-user.adoc[Diagram Subset Control guide] for full details. + +[cols="2,1,2,4"] +|=== +| Setting | Type | Default | Description + +| `diagramSubsets` +| `map` +| `{}` +| Whitelist: include only these sub-resource diagrams + +| `diagramExclusions` +| `map` +| `{}` +| Blacklist: exclude these sub-resource diagrams + +| `globalDiagramExclusions` +| `string[]` +| `[]` +| Exclude these sub-resource types from all resources +|=== + +=== Document Metadata + +[cols="2,1,2,4"] +|=== +| Setting | Type | Default | Description + +| `iprMode` +| `string` +| `RAND` +| IPR mode for the document header + +| `metaData` +| `string[]` +| `[RELEASE, REVISION, IPR-MODE, STATUS, ...]` +| Keys extracted from existing user guide for carry-forward + +| `allowedInfo` +| `string[]` +| `[x-api-id, x-parent-api, ...]` +| OAS `info` x-fields included in document metadata +|=== + +== Config File Format + +User config files use a mix of direct keys and namespaced keys for backward compatibility: + +[source,yaml] +---- +# Exclude additional resources (replaces default list) +"userguide::excludedResources": + - EventSubscription + - Hub + - Monitor + +# Add custom resource mappings (shallow merged) +resourceMapping: + EventSubscription: Hub + Monitor: PerformanceMonitor + +# Override meta properties (replaces default list) +"userguide::metaProperties": + - "@type" + - "@baseType" + - "@schemaLocation" + - "@referredType" + +# Add custom format mappings (shallow merged) +formatToType: + date-time: DateTime + duration: Duration + +# Reduce enum display +truncateEnumsCount: 10 +truncateEnumsTrigger: 20 + +# Customize soft breaks +insertSoftBreakHints: true +softBreakHints: + marker: "\u00AD" + splitCamelCase: true + splitAlphaNumeric: false + +# Enable convention-based resource sample fallback +useResourceSampleFallback: true + +# Diagram filtering (see dedicated guide) +diagramSubsets: + Widget: + - Feature + - Characteristic + +globalDiagramExclusions: + - ContactMedium +---- + +Multiple config files can be passed; they are applied in order (last wins for replace behavior, additive for shallow merge). diff --git a/partY-userguide-user.adoc b/partY-userguide-user.adoc new file mode 100644 index 0000000..393e436 --- /dev/null +++ b/partY-userguide-user.adoc @@ -0,0 +1,114 @@ += User Guide Generation — End-User Guide + +This document describes what the user guide generator produces, how to understand its output, and practical tips for working with it. + +== What the Tool Produces + +The user guide generator reads an OpenAPI specification, a rules YAML file, and an optional diagrams YAML manifest, then produces a complete AsciiDoc user guide document including: + +* Resource description pages with field tables and sub-resource detail +* Resource diagrams (when a `diagrams.yaml` is provided) +* Operation pages (GET, POST, PATCH, PUT, DELETE) with mandatory attributes, patchable/non-patchable tables, and request/response samples +* Notification documentation + +== Generation Pipeline + +. *Load configuration* — Embedded defaults + user config files merged in order +. *Parse inputs* — OpenAPI spec, rules YAML, and diagrams YAML are parsed +. *Filter resources* — Resources in `excludedResources` are removed; remaining resources are ordered per the rules file +. *Discover discriminator subtypes* — Concrete types from discriminator mappings are injected into the document resource list +. *Build per-resource data* — For each resource: field descriptions, sub-resource details, operation data (mandatory attributes, patchable/non-patchable, samples), notification associations +. *Generate per-resource `.adoc` files* — One `.adoc` per resource rendered from the resource template +. *Generate per-resource `_diagram.adoc` files* — Diagram references rendered with filtering applied (see diagram subset control) +. *Render aggregate templates* — `Resources.adoc`, `Operations.adoc`, `Notifications.adoc`, `Environment.adoc`, `Notice.adoc` +. *Render target templates* — Main document template, `config/Environment.adoc`, `config/Copyright.adoc` (only written if not already present) +. *Copy static files* — Section part files and notification pattern images + +== Logging Output + +[source,text] +---- +User guide generated: 42 files (312ms) + • generated/Widget.adoc + • generated/Widget_diagram.adoc + • generated/Gadget.adoc + • generated/Gadget_diagram.adoc + • generated/Resources.adoc + • generated/Operations.adoc + • generated/Notifications.adoc + • generated/Environment.adoc + • generated/Notice.adoc + • target/userguide.adoc + • target/config/Environment.adoc + • target/config/Copyright.adoc + • target/parts/01_Introduction.adoc + • target/parts/02_UseCases.adoc + • ... +---- + +=== Warnings + +Warnings are collected during generation and reported alongside the result. Diagram filtering warnings indicate which sub-resource diagrams were excluded: + +[source,text] +---- +Diagram filter (diagramSubsets): Widget — excluded 5 sub-resource diagram(s): Characteristic, ContactMedium, Feature, Intent, PlaceRefOrValue +Diagram filter (diagramExclusions): Gadget — excluded 2 sub-resource diagram(s): Characteristic, ContactMedium +---- + +== Output Structure + +=== Generated Directory + +Contains AsciiDoc fragments regenerated on every run: + +[source,text] +---- +generated/ +├── Widget.adoc # Per-resource field tables and sub-resource detail +├── Widget_diagram.adoc # Per-resource diagram references +├── Gadget.adoc +├── Gadget_diagram.adoc +├── Resources.adoc # Aggregate resource include list +├── Operations.adoc # Aggregate operations documentation +├── Notifications.adoc # Aggregate notification documentation +├── Environment.adoc # Generated environment metadata +├── Notice.adoc # Legal notice +└── images/ + ├── NotificationsPattern.svg + ├── NotificationsPattern.png + └── NotificationsPattern.puml +---- + +=== Target Directory + +Contains the main document, editable configuration files, and section parts: + +[source,text] +---- +target/ +├── userguide.adoc # Main document (includes generated fragments) +├── config/ +│ ├── Environment.adoc # Editable environment/release metadata +│ └── Copyright.adoc # Editable copyright notice +└── parts/ + ├── 01_Introduction.adoc + ├── 02_UseCases.adoc + ├── 03_PolymorphismAndExtensions.adoc + ├── 04_Resources.adoc + ├── 05_Operations.adoc + ├── 06_Common_notifications.adoc + └── 07_Acknowledgements.adoc +---- + +NOTE: Files in `config/` and `parts/` are only written on first generation. They can be freely edited afterward without being overwritten. + +== Tips + +* Run diagram generation before user guide generation so that `diagrams.yaml` is available +* Check for warnings about diagram filtering to verify your `diagramSubsets`/`diagramExclusions` config is working correctly +* Place your project config file at `documentation/userguide/config.yaml` — the tooling discovers it automatically from that location + +== See Also + +For detailed configuration reference (resource filtering, display format, type mappings, diagram subset control, etc.), see the link:partY-userguide-admin.adoc[Administrator / Developer Configuration Guide].