docs(website): add design blog series, hub filtering, and polish (#173) #115
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: Deploy Documentation | |
| on: | |
| push: | |
| branches: [main] | |
| workflow_dispatch: | |
| permissions: | |
| contents: write | |
| concurrency: | |
| group: docs-deploy | |
| cancel-in-progress: true | |
| jobs: | |
| deploy: | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout | |
| uses: actions/checkout@v4 | |
| - name: Set up JDK 21 | |
| uses: actions/setup-java@v4 | |
| with: | |
| java-version: '21' | |
| distribution: temurin | |
| cache: maven | |
| - name: Set up Node.js | |
| uses: actions/setup-node@v4 | |
| with: | |
| node-version: '22' | |
| cache: npm | |
| cache-dependency-path: website/package-lock.json | |
| - name: Install website dependencies | |
| run: npm ci | |
| working-directory: website | |
| - name: Resolve released version | |
| id: version | |
| run: echo "value=$(node -p 'require("./website/versions.json")[0]')" >> "$GITHUB_OUTPUT" | |
| - name: Build project (skip tests) | |
| run: mvn install -DskipTests -q -Drevision=${{ steps.version.outputs.value }} | |
| - name: Generate Javadoc (aggregate) | |
| run: | | |
| # Publish only the public Java API: | |
| # storm-foundation -> st.orm, st.orm.mapping (Entity, Ref, annotations) | |
| # storm-java21 -> st.orm.repository, st.orm.template (ORMTemplate, | |
| # query builder, repositories) | |
| # Everything else is excluded on purpose: | |
| # - Kotlin modules (Ktor, compiler-plugin variants) have no module | |
| # descriptor and break aggregation ("named and unnamed modules"); | |
| # they are published separately as KDoc under /api/kotlin. | |
| # - storm-core is the internal engine (st.orm.core.*). | |
| # - dialect SPIs, storm-test and storm-metamodel-processor are not | |
| # part of the user-facing API; Spring/Jackson are integrations. | |
| # Keep >= 2 named modules so javadoc stays in module mode and pages keep | |
| # their <module>/<package> paths (the docs link to storm.foundation/...). | |
| mvn javadoc:aggregate -q \ | |
| -Drevision=${{ steps.version.outputs.value }} \ | |
| -Dmaven.javadoc.failOnError=false \ | |
| -DadditionalJOption=--enable-preview \ | |
| -Ddoclint=none \ | |
| -pl '!:storm-kotlin,!:storm-kotlin-spring,!:storm-kotlin-spring-boot-starter,!:storm-kotlinx-serialization,!:storm-metamodel-ksp,!:storm-spring-boot-starter,!:storm-jackson3,!:storm-ktor,!:storm-ktor-test,!:storm-ktor-koin,!:storm-compiler-plugin-2.0,!:storm-compiler-plugin-2.1,!:storm-compiler-plugin-2.2,!:storm-compiler-plugin-2.3,!:storm-compiler-plugin-2.4,!:storm-metamodel-processor,!:storm-core,!:storm-test,!:storm-jackson2,!:storm-oracle,!:storm-mssqlserver,!:storm-postgresql,!:storm-mysql,!:storm-mariadb,!:storm-sqlite,!:storm-h2,!:storm-spring' | |
| - name: Copy Javadoc to website/static/api/java | |
| run: | | |
| mkdir -p website/static/api/java | |
| # The aggregate report goal writes under the reporting output dir: | |
| # target/site/apidocs on Maven 3.x, target/reports/apidocs on Maven 4.x. | |
| copied="" | |
| # Require index.html specifically: a failed aggregate can still leave | |
| # an empty apidocs dir, and a plain -d check would treat that as success | |
| # and deploy an empty /api/java. | |
| for src in target/site/apidocs target/reports/apidocs; do | |
| if [ -f "$src/index.html" ]; then | |
| cp -r "$src"/* website/static/api/java/ | |
| copied="$src" | |
| break | |
| fi | |
| done | |
| if [ -z "$copied" ]; then | |
| echo "::error::Aggregate Javadoc not found (checked target/site/apidocs and target/reports/apidocs); /api/java/index.html would 404" | |
| exit 1 | |
| fi | |
| echo "Copied aggregate Javadoc from $copied" | |
| - name: Copy KDoc to website/static/api/kotlin | |
| run: | | |
| for module in storm-kotlin storm-kotlin-spring storm-kotlin-spring-boot-starter storm-metamodel-ksp storm-kotlinx-serialization; do | |
| if [ -d "$module/target/dokka" ]; then | |
| mkdir -p "website/static/api/kotlin/$module" | |
| cp -r "$module/target/dokka/"* "website/static/api/kotlin/$module/" | |
| fi | |
| done | |
| - name: Generate llms-full.txt | |
| run: bash scripts/generate-llms-full.sh | |
| working-directory: website | |
| - name: Build Docusaurus | |
| run: npm run build | |
| working-directory: website | |
| - name: Deploy to GitHub Pages | |
| uses: peaceiris/actions-gh-pages@v4 | |
| with: | |
| github_token: ${{ secrets.GITHUB_TOKEN }} | |
| publish_dir: ./website/build | |
| force_orphan: true |