diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index 5fd3b8b..5b033fd 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -58,8 +58,18 @@ jobs: - name: Generate site run: ./dtcw4 local generateSite - - name: Fail if the landing page is missing - run: test -s build/docs/microsite/output/index.html + # generateSite reports success even when the landing page template fails + # to parse - it then writes an index.html without any landing content. + # Check for the content, not just for the file. + - name: Fail if the landing page is missing or empty + run: | + index=build/docs/microsite/output/index.html + test -s "$index" + grep -q 'dtc-landing' "$index" || { + echo "::error::index.html carries no landing page content -" \ + "the template in docs/site/doc/ probably failed to parse." + exit 1 + } - name: Upload site as build artifact uses: actions/upload-artifact@v4 diff --git a/docToolchainConfig.groovy b/docToolchainConfig.groovy index a93c2ab..df6b74d 100644 --- a/docToolchainConfig.groovy +++ b/docToolchainConfig.groovy @@ -23,7 +23,11 @@ microsite = [:] // title in the upper left corner and fallback page title microsite.title = 'arc42-generator' -// the landing page ships with the internal theme +// project landing page: site/ overlays the internal theme, so +// site/doc/landingpage.gsp replaces the theme's placeholder page. The path is +// relative to docs/, and pointing outside it keeps the template out of the +// published site - inside docs/ it would be copied along as a stray asset. +microsite.siteFolder = '../site' microsite.landingPage = 'landingpage.gsp' // footer and edit links diff --git a/site/doc/landingpage.gsp b/site/doc/landingpage.gsp new file mode 100644 index 0000000..452792a --- /dev/null +++ b/site/doc/landingpage.gsp @@ -0,0 +1,138 @@ +
+ + +
+ + + โ€” ARC42-GENERATOR โ€” + + ยง ARCHITECTURE / SPECIFICATION / BACKLOG +

One source,
every shape.

+

+ The arc42 template is maintained once, as AsciiDoc, in the + arc42-template repository โ€” the + Golden Master. Readers want it as Word, Markdown, HTML, LaTeX and a + dozen other formats, in their own language, with or without the embedded help texts. + This generator produces every one of those combinations and packs each into a ZIP + archive ready for download. +

+
+ ๐Ÿ“˜ Architecture + Just want a template? โ†’ +
+
+ +
โ›“โ›“โ›“
+ + +
+

Four phases, one command

+

Every language of the Golden Master, in two flavors, converted into seventeen formats.

+
+
+
โœ‚๏ธ
Generatestrip feature flags
+
๐Ÿ”
Discoverscan and validate
+
๐Ÿ”„
Convertasciidoctor + pandoc
+
๐Ÿ“ฆ
Packageone zip per variant
+
+ +
โ›“โ›“โ›“
+ + +
+

What you'll find here

+

+ This documentation was recovered from the source code, not written alongside it. + Every claim carries its evidence as file:line; facts only the team could + supply are marked (team answer). +

+
+
+
+
๐Ÿงฉ
+

Architecture

+

+ All twelve arc42 chapters. Context and building blocks as C4 diagrams, five + cross-cutting concepts, seven ADRs with Pugh matrices, and chapter 11 separating + risks from technical debt. +

+
+
+
๐ŸŽฏ
+

Product Requirements

+

+ The problem, four personas, the goals and where the product falls short of them + today. Success is measured in release effort, not in downloads. +

+
+
+
๐Ÿ“‹
+

Specification

+

+ Four persona use cases in Cockburn form, six system use cases for the technical + interfaces, ten business rules, Gherkin criteria and twelve EARS requirements. +

+
+
+
๐Ÿ—‚๏ธ
+

Backlog

+

+ Four EPICs, sixteen user stories, prioritized with MoSCoW. The first EPIC exists + because the build reports success even when conversions failed. +

+
+
+
๐ŸŒณ
+

Question Tree

+

+ How the documentation was recovered: five root questions refined until every leaf + could be answered from one specific place in the code โ€” or marked open. +

+
+
+
โ“
+

Open Questions

+

+ The nine questions the code could not answer, one section per role โ€” all of them + answered by the team, and those answers feed the documents above. +

+
+
+ +
โ›“โ›“โ›“
+ + +
+

Build it yourself

+

Docker is the supported way to run the generator; the documentation builds with docToolchain.

+
+
+
+
๐Ÿณ
+

The templates

+

+ docker compose up refreshes the Golden Master, generates both + flavors, converts every format and writes the archives to + arc42-template/dist/. +

+
+
+
๐Ÿ“–
+

This site

+

+ ./dtcw4 local generateSite renders docs/ into a + microsite. A GitHub Action does the same on every push and publishes the result + here. +

+
+
+
๐Ÿ”ง
+

Contribute

+

+ A new translation needs no change in this repository โ€” a directory matching + /^[A-Z]{2,}$/ in the Golden Master is picked up by itself. +

+
+
+ +