Run tests for the moved documentation (#19278)

Closes #19272

.github/actions/conditional/action.yml

@@ -17,9 +17,12 @@ outputs:
   codeql-themes:
     description: Should "codeql-analysis.yml / themes" execute
     value: ${{ steps.changes.outputs.codeql-themes }}
-  docs:
-    description: Should "docs.yml" execute
-    value: ${{ steps.changes.outputs.docs }}
+  guides:
+    description: Should "guides.yml" execute
+    value: ${{ steps.changes.outputs.guides }}
+  documentation:
+    description: Should "documentation.yml" execute
+    value: ${{ steps.changes.outputs.documentation }}
 
 runs:
   using: composite

.github/actions/conditional/conditions

@@ -2,18 +2,21 @@
 #
 # To test a pattern run '.github/actions/conditional/conditional.sh <remote name> <branch>'
 
-.github/actions/                            ci operator js codeql-java codeql-themes
+.github/actions/                            ci operator js codeql-java codeql-themes guides documentation
 
 .github/workflows/ci.yml                    ci
 .github/workflows/operator-ci.yml           operator
 .github/workflows/js-ci.yml                 js
 .github/workflows/codeql-analysis.yml       codeql-java codeql-themes
+.github/workflows/guides.yml                guides
+.github/workflows/documentation.yml         documentation
 
 */src/main/                                 ci operator
 */src/test/                                 ci operator
 pom.xml                                     ci operator
 
-docs/guides/                                docs
+docs/guides/                                guides
+docs/documentation/                         documentation
 
 js/                                         js
 

.github/workflows/documentation.yml

@@ -0,0 +1,141 @@
+name: Keycloak Documentation
+
+on:
+  push:
+    branches-ignore:
+      - main
+      - dependabot/**
+  pull_request:
+  schedule:
+    - cron: 0 5 * * *
+  workflow_dispatch:
+
+env:
+  DEFAULT_JDK_VERSION: 17
+  DEFAULT_JDK_DIST: temurin
+
+concurrency:
+  # Only cancel jobs for PR updates
+  group: documentation-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+
+  conditional:
+    name: Check conditional workflows and jobs
+    if: github.event_name != 'schedule' || github.repository == 'keycloak/keycloak'
+    runs-on: ubuntu-latest
+    outputs:
+      documentation: ${{ steps.conditional.outputs.documentation }}
+    steps:
+      - uses: actions/checkout@v3
+
+      - id: conditional
+        uses: ./.github/actions/conditional
+
+  build:
+    name: Build
+    if: ${{ needs.conditional.outputs.documentation == 'true' }}
+    runs-on: ubuntu-latest
+    needs: conditional
+    steps:
+      - uses: actions/checkout@v3
+
+      - id: setup-java
+        name: Setup Java
+        uses: actions/setup-java@v3
+        with:
+          distribution: ${{ env.DEFAULT_JDK_DIST }}
+          java-version: ${{ env.DEFAULT_JDK_VERSION }}
+
+      - id: maven-cache
+        name: Maven cache
+        uses: ./.github/actions/maven-cache
+
+      - id: build-documentation
+        name: Build Keycloak
+        shell: bash
+        run: |
+          MVN_HTTP_CONFIG="-Dhttp.keepAlive=false -Dmaven.wagon.http.pool=false -Dmaven.wagon.http.retryHandler.class=standard -Dmaven.wagon.http.retryHandler.count=3 -Dmaven.wagon.httpconnectionManager.ttlSeconds=120"
+          ./mvnw install -DskipTests -am -pl docs/documentation/tests,docs/documentation/dist -nsu -B -e $MVN_HTTP_CONFIG -Pdocumentation
+
+      - id: test-documentation
+        name: Verify Keycloak documentation
+        shell: bash
+        run: |
+          ./mvnw test -Dtest=!ExternalLinksTest -am -pl docs/documentation/tests,docs/documentation/dist -nsu -B -e -Pdocumentation 
+
+      - id: upload-keycloak-documentation
+        name: Upload Keycloak documentation
+        uses: actions/upload-artifact@v3
+        with:
+          name: keycloak-documentation
+          path: docs/documentation/dist/target/*.zip
+          retention-days: 1
+
+  external-links:
+    name: External links check
+    if: ${{ needs.conditional.outputs.documentation == 'true' }}
+    runs-on: ubuntu-latest
+    needs: conditional
+    steps:
+      - uses: actions/checkout@v3
+
+      - id: setup-java
+        name: Setup Java
+        uses: actions/setup-java@v3
+        with:
+          distribution: ${{ env.DEFAULT_JDK_DIST }}
+          java-version: ${{ env.DEFAULT_JDK_VERSION }}
+
+      - id: maven-cache
+        name: Maven cache
+        uses: ./.github/actions/maven-cache
+
+      - id: build-documentation
+        name: Build Keycloak
+        shell: bash
+        run: |
+          MVN_HTTP_CONFIG="-Dhttp.keepAlive=false -Dmaven.wagon.http.pool=false -Dmaven.wagon.http.retryHandler.class=standard -Dmaven.wagon.http.retryHandler.count=3 -Dmaven.wagon.httpconnectionManager.ttlSeconds=120"
+          ./mvnw install -DskipTests -am -pl docs/documentation/tests -nsu -B -e -Pdocumentation $MVN_HTTP_CONFIG 
+
+      - id: test-documentation
+        name: Verify Keycloak documentation
+        shell: bash
+        run: |
+          ./mvnw test -Dtest=ExternalLinksTest -am -pl docs/documentation/tests,docs/documentation/dist -nsu -B -e -Pdocumentation
+
+  check-set-status:
+    name: Set check conclusion
+    needs:
+      - build
+    runs-on: ubuntu-latest
+    outputs:
+      conclusion: ${{ steps.check.outputs.conclusion }}
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - id: check
+        uses: ./.github/actions/checks-success
+
+  check:
+    name: Status Check - Keycloak Documentation
+    if: always() && ( github.event_name != 'schedule' || github.repository == 'keycloak/keycloak' )
+    needs:
+      - conditional
+      - check-set-status
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Check status
+        uses: ./.github/actions/checks-job-pass
+        with:
+          required: ${{ needs.conditional.outputs.documentation == 'true' }}
+          conclusion: ${{ needs.check-set-status.outputs.conclusion }}

.github/workflows/guides.yml

@@ -1,4 +1,4 @@
-name: Keycloak Docs
+name: Keycloak Guides
 
 on:
   push:
@@ -14,7 +14,7 @@ env:
 
 concurrency:
   # Only cancel jobs for PR updates
-  group: docs-${{ github.head_ref || github.run_id }}
+  group: guides-${{ github.head_ref || github.run_id }}
   cancel-in-progress: true
 
 defaults:
@@ -28,7 +28,7 @@ jobs:
     if: github.event_name != 'schedule' || github.repository == 'keycloak/keycloak'
     runs-on: ubuntu-latest
     outputs:
-      docs: ${{ steps.conditional.outputs.docs }}
+      guides: ${{ steps.conditional.outputs.guides }}
       ci: ${{ steps.conditional.outputs.ci }}
     steps:
       - uses: actions/checkout@v3
@@ -38,8 +38,8 @@ jobs:
 
   build:
     name: Build
-    # will only build the docs if the general CI doesn't run, which will also build the docs
-    if: ${{ needs.conditional.outputs.docs == 'true' && needs.conditional.outputs.ci != 'true' }}
+    # will only build the guides if the general CI doesn't run, which will also build the guides
+    if: ${{ needs.conditional.outputs.guides == 'true' && needs.conditional.outputs.ci != 'true' }}
     runs-on: ubuntu-latest
     needs: conditional
     steps:
@@ -63,7 +63,7 @@ jobs:
         uses: ./.github/actions/checks-success
 
   check:
-    name: Status Check - Keycloak Docs
+    name: Status Check - Keycloak Guides
     if: always() && ( github.event_name != 'schedule' || github.repository == 'keycloak/keycloak' )
     needs:
       - conditional
@@ -76,5 +76,5 @@ jobs:
       - name: Check status
         uses: ./.github/actions/checks-job-pass
         with:
-          required: ${{ needs.conditional.outputs.docs == 'true' && needs.conditional.outputs.ci != 'true' }}
+          required: ${{ needs.conditional.outputs.guides == 'true' && needs.conditional.outputs.ci != 'true' }}
           conclusion: ${{ needs.check-set-status.outputs.conclusion }}

docs/documentation/README.md

@@ -30,17 +30,17 @@ If you are using Windows, you need to run the following command with administrat
 
 To build Keycloak Documentation run:
 
-    mvn clean install
+    mvn clean install -am -pl docs/documentation/dist -Pdocumentation
 
 Or to build a specific guide run:
 
-    mvn clean install -f GUIDE_DIR
+    mvn clean install -pl doc/documentation/GUIDE_DIR -Pdocumentation
     
 By default, an archive version of the documentation is built. To build the latest build run:
 
-    mvn clean install -Dlatest
+    mvn clean install ... -Platest,documentation
 
-You can then view the documentation by opening GUIDE_DIR/target/generated-docs/index.html.
+You can then view the documentation by opening `doc/documentation/GUIDE_DIR/target/generated-docs/index.html`.
 
 
 License

docs/documentation/aggregation/pom.xml

@@ -6,7 +6,7 @@
         <groupId>org.keycloak.documentation</groupId>
         <artifactId>documentation-parent</artifactId>
         <version>999.0.0-SNAPSHOT</version>
-        <relativePath>../</relativePath>
+        <relativePath>../pom.xml</relativePath>
     </parent>
 
     <name>Aggregation</name>

docs/documentation/api_documentation/pom.xml

@@ -6,7 +6,7 @@
         <groupId>org.keycloak.documentation</groupId>
         <artifactId>documentation-parent</artifactId>
         <version>999.0.0-SNAPSHOT</version>
-        <relativePath>../</relativePath>
+        <relativePath>../pom.xml</relativePath>
     </parent>
 
     <name>API Documentation</name>

docs/documentation/authorization_services/pom.xml

@@ -6,7 +6,7 @@
         <groupId>org.keycloak.documentation</groupId>
         <artifactId>documentation-parent</artifactId>
         <version>999.0.0-SNAPSHOT</version>
-        <relativePath>../</relativePath>
+        <relativePath>../pom.xml</relativePath>
     </parent>
 
     <name>Authorization Services</name>

docs/documentation/dist/pom.xml

@@ -6,13 +6,22 @@
         <groupId>org.keycloak.documentation</groupId>
         <artifactId>documentation-parent</artifactId>
         <version>999.0.0-SNAPSHOT</version>
-        <relativePath>../</relativePath>
+        <relativePath>../pom.xml</relativePath>
     </parent>
 
     <name>Keycloak Documentation dist</name>
     <artifactId>keycloak-documentation</artifactId>
     <packaging>pom</packaging>
 
+    <dependencies>
+        <dependency>
+            <groupId>org.keycloak.documentation</groupId>
+            <artifactId>aggregation</artifactId>
+            <version>${project.version}</version>
+            <type>pom</type>
+        </dependency>
+    </dependencies>
+
     <build>
         <plugins>
             <plugin>

docs/documentation/pom.xml

@@ -109,6 +109,7 @@
                             </goals>
                             <configuration>
                                 <target>
+                                    <!-- print the link on the console to be able to open it in the local browser -->
                                     <echo>OUTPUT: file://${project.build.directory}/generated-docs/${masterFile}.html ${projectLatestBuild}</echo>
                                 </target>
                             </configuration>
@@ -136,7 +137,7 @@
                                 <goal>header</goal>
                             </goals>
                             <configuration>
-                                <masterFile>${masterFile}</masterFile>
+                                <masterFileName>${masterFile}</masterFileName>
                             </configuration>
                         </execution>
                     </executions>

docs/documentation/release_notes/pom.xml

@@ -6,7 +6,7 @@
         <groupId>org.keycloak.documentation</groupId>
         <artifactId>documentation-parent</artifactId>
         <version>999.0.0-SNAPSHOT</version>
-        <relativePath>../</relativePath>
+        <relativePath>../pom.xml</relativePath>
     </parent>
 
     <name>Release Notes</name>

docs/documentation/securing_apps/pom.xml

@@ -6,7 +6,7 @@
         <groupId>org.keycloak.documentation</groupId>
         <artifactId>documentation-parent</artifactId>
         <version>999.0.0-SNAPSHOT</version>
-        <relativePath>../</relativePath>
+        <relativePath>../pom.xml</relativePath>
     </parent>
 
     <name>Securing Applications and Services</name>

docs/documentation/server_admin/pom.xml

@@ -6,7 +6,7 @@
         <groupId>org.keycloak.documentation</groupId>
         <artifactId>documentation-parent</artifactId>
         <version>999.0.0-SNAPSHOT</version>
-        <relativePath>../</relativePath>
+        <relativePath>../pom.xml</relativePath>
     </parent>
 
     <name>Server Administration</name>

docs/documentation/server_development/pom.xml

@@ -6,7 +6,7 @@
         <groupId>org.keycloak.documentation</groupId>
         <artifactId>documentation-parent</artifactId>
         <version>999.0.0-SNAPSHOT</version>
-        <relativePath>../</relativePath>
+        <relativePath>../pom.xml</relativePath>
     </parent>
 
     <name>Server Developer</name>

docs/documentation/tests/pom.xml

@@ -8,15 +8,6 @@
 
     <build>
         <plugins>
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-compiler-plugin</artifactId>
-                <configuration>
-                    <source>1.8</source>
-                    <target>1.8</target>
-                </configuration>
-            </plugin>
-
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-jar-plugin</artifactId>
@@ -65,10 +56,10 @@
         <groupId>org.keycloak.documentation</groupId>
         <artifactId>documentation-parent</artifactId>
         <version>999.0.0-SNAPSHOT</version>
-        <relativePath>../</relativePath>
+        <relativePath>../pom.xml</relativePath>
     </parent>
 
-    <name>Tests</name>
+    <name>Keycloak Documentation tests</name>
     <artifactId>tests</artifactId>
     <packaging>jar</packaging>
 
@@ -103,6 +94,18 @@
             <version>${project.version}</version>
             <type>pom</type>
         </dependency>
+        <dependency>
+            <groupId>org.keycloak.documentation</groupId>
+            <artifactId>upgrading</artifactId>
+            <version>${project.version}</version>
+            <type>pom</type>
+        </dependency>
+        <dependency>
+            <groupId>org.keycloak.documentation</groupId>
+            <artifactId>release-notes</artifactId>
+            <version>${project.version}</version>
+            <type>pom</type>
+        </dependency>
 
         <dependency>
             <groupId>org.junit.jupiter</groupId>
@@ -140,6 +143,10 @@
             <version>5.0.1</version>
             <scope>test</scope>
         </dependency>
+        <dependency>
+            <groupId>org.slf4j</groupId>
+            <artifactId>slf4j-log4j12</artifactId>
+        </dependency>
     </dependencies>
 
 </project>

docs/documentation/tests/src/test/resources/log4j.properties

@@ -1,4 +1,4 @@
-log4j.rootLogger=debug, keycloak
+log4j.rootLogger=info, keycloak
 
 log4j.appender.keycloak=org.apache.log4j.ConsoleAppender
 log4j.appender.keycloak.layout=org.apache.log4j.PatternLayout

docs/documentation/upgrading/pom.xml

@@ -6,7 +6,7 @@
         <groupId>org.keycloak.documentation</groupId>
         <artifactId>documentation-parent</artifactId>
         <version>999.0.0-SNAPSHOT</version>
-        <relativePath>../</relativePath>
+        <relativePath>../pom.xml</relativePath>
     </parent>
 
     <name>Upgrading Guide</name>

docs/pom.xml

@@ -32,6 +32,20 @@
     <modules>
         <module>maven-plugin</module>
         <module>guides</module>
-        <module>documentation</module>
     </modules>
+
+    <profiles>
+        <profile>
+            <id>documentation</id>
+            <modules>
+                <module>documentation</module>
+            </modules>
+        </profile>
+        <profile>
+            <id>all</id>
+            <modules>
+                <module>documentation</module>
+            </modules>
+        </profile>
+    </profiles>
 </project>