Move guides to /docs/guides so they are simpler to find and maintain (#17378)

CIAM-5057

.github/CODEOWNERS

@@ -32,8 +32,8 @@
 
 /operator/                                                  @keycloak/cloud-native-maintainers
 /quarkus/                                                   @keycloak/cloud-native-maintainers
-/docs/guides/src/main/server/                               @keycloak/cloud-native-maintainers
+/docs/guides/server/                                        @keycloak/cloud-native-maintainers
-/docs/guides/src/main/operator/                             @keycloak/cloud-native-maintainers
+/docs/guides/operator/                                      @keycloak/cloud-native-maintainers
 
 ###################################################################################################
 # Store (@keycloak/store-maintainers)

.github/actions/conditional/action.yml

@@ -20,6 +20,9 @@ outputs:
   codeql-js_adapter:
     description: Should "codeql-analysis.yml / js-adapter" execute
     value: ${{ steps.changes.outputs.codeql-js_adapter }}
+  docs:
+    description: Should "docs.yml" execute
+    value: ${{ steps.changes.outputs.docs }}
 
 runs:
   using: composite

.github/actions/conditional/conditions

@@ -13,6 +13,8 @@
 */src/test/                                 ci operator
 pom.xml                                     ci operator
 
+docs/guides/                                docs
+
 js/                                         js
 
 *.java                                      codeql-java

.github/workflows/docs.yml

@@ -0,0 +1,80 @@
+name: Keycloak Docs
+
+on:
+  push:
+    branches-ignore:
+      - main
+      - dependabot/**
+  pull_request:
+  workflow_dispatch:
+
+env:
+  DEFAULT_JDK_VERSION: 17
+  DEFAULT_JDK_DIST: temurin
+
+concurrency:
+  # Only cancel jobs for PR updates
+  group: docs-${{ 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:
+      docs: ${{ steps.conditional.outputs.docs }}
+      ci: ${{ steps.conditional.outputs.ci }}
+    steps:
+      - uses: actions/checkout@v3
+
+      - id: conditional
+        uses: ./.github/actions/conditional
+
+  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' }}
+    runs-on: ubuntu-latest
+    needs: conditional
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Build Keycloak
+        uses: ./.github/actions/build-keycloak
+
+  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 Docs
+    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.docs == 'true' && needs.conditional.outputs.ci != 'true' }}
+          conclusion: ${{ needs.check-set-status.outputs.conclusion }}

docs/guides/GENERATE-DOCS.md

@@ -9,9 +9,9 @@ To build the guides, run:
 cd docs
 mvn clean install
 ```
-After that you will have the following artifacts:
+After that, you will have the following artifacts:
 
 - `docs/guides/target/generated-guides`: pure asciidoc generated versions of the guides
-- `docs/guides/target/generated-docs/<operator|server>/index.html`: all guides in a single html file generated with asciidoc maven plugins. 
+- `docs/guides/target/generated-docs/<operator|server|migration|getting-started>/index.html`: all guides in a single html file generated with asciidoc maven plugins. 
 
 _Note:_ The layout primarily serves as an example for now and is not how we will eventually present the documentation.

docs/guides/pom.xml

@@ -1,5 +1,5 @@
 <!--
-  ~ Copyright 2016 Red Hat, Inc. and/or its affiliates
+  ~ Copyright 2023 Red Hat, Inc. and/or its affiliates
   ~ and other contributors as indicated by the @author tags.
   ~
   ~ Licensed under the Apache License, Version 2.0 (the "License");
@@ -46,16 +46,18 @@
                 <executions>
                     <execution>
                         <id>copy-resources</id>
-                        <!-- here the phase you need -->
+                        <!-- As of 3.3.0, if there is no phase specified, it will not execute.
+                        Even if there is a phase specified, it will always execute in phase process-resources,
+                        thereby executing before the keycloak-guides-maven-plugin -->
                         <phase>validate</phase>
                         <goals>
                             <goal>copy-resources</goal>
                         </goals>
                         <configuration>
-                            <outputDirectory>${basedir}/src/main/images</outputDirectory>
+                            <outputDirectory>${basedir}/target/generated-docs/images</outputDirectory>
                             <resources>
                                 <resource>
-                                    <directory>${basedir}/target/generated-guides/images</directory>
+                                    <directory>${basedir}/images</directory>
                                 </resource>
                             </resources>
                         </configuration>
@@ -72,6 +74,9 @@
                         <goals>
                             <goal>keycloak-guide</goal>
                         </goals>
+                        <configuration>
+                            <sourceDir>${project.basedir}</sourceDir>
+                        </configuration>
                     </execution>
                 </executions>
             </plugin>

docs/guides/src/test/java/org/keycloak/guides/DocsBuildDebugUtil.java

@@ -9,14 +9,19 @@ import java.io.IOException;
 public class DocsBuildDebugUtil {
 
     public static void main(String[] args) throws IOException, TemplateException {
-        String userDir = System.getProperty("user.dir");
         File usrDir = new File(System.getProperty("user.dir"));
-        File srcDir = usrDir.toPath().resolve("docs/guides/src/main").toFile();
+
-        File targetDir = usrDir.toPath().resolve("target/generated-guides-tests").toFile();
+        for (File srcDir: usrDir.toPath().resolve("docs/guides").toFile().listFiles(d -> d.isDirectory() && !d.getName().equals("templates"))) {
-        targetDir.mkdirs();
+            if (srcDir.getName().equals("target") || srcDir.getName().equals("src")) {
-        GuideBuilder builder = new GuideBuilder(srcDir, targetDir, null);
+                // those are standard maven folders, ignore them
-        builder.build();
+                continue;
-        System.out.println("Guides generated to: " + targetDir.getAbsolutePath().toString());
+            }
+            File targetDir = usrDir.toPath().resolve("target/generated-guides/" + srcDir.getName()).toFile();
+            targetDir.mkdirs();
+            GuideBuilder builder = new GuideBuilder(srcDir, targetDir, null);
+            builder.build();
+            System.out.println("Guides generated to: " + targetDir.getAbsolutePath().toString());
+        }
     }
 
 }

docs/maven-plugin/src/main/java/org/keycloak/guides/maven/GuideMojo.java

@@ -23,9 +23,14 @@ public class GuideMojo extends AbstractMojo {
     public void execute() throws MojoFailureException {
         try {
             Log log = getLog();
-            File topDir = new File(sourceDir).getParentFile();
+            File topDir = new File(sourceDir);
 
             for (File srcDir: topDir.listFiles(d -> d.isDirectory() && !d.getName().equals("templates"))) {
+                if (srcDir.getName().equals("target") || srcDir.getName().equals("src")) {
+                    // those are standard maven folders, ignore them
+                    continue;
+                }
+
                 File targetDir = new File(new File(this.targetDir, "generated-guides"), srcDir.getName());
                 if (!targetDir.isDirectory()) {
                     targetDir.mkdirs();