diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 518c2b600b..266b76745e 100644 --- a/.github/CODEOWNERS +++ b/.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/src/main/operator/ @keycloak/cloud-native-maintainers +/docs/guides/server/ @keycloak/cloud-native-maintainers +/docs/guides/operator/ @keycloak/cloud-native-maintainers ################################################################################################### # Store (@keycloak/store-maintainers) diff --git a/.github/actions/conditional/action.yml b/.github/actions/conditional/action.yml index 9c7340edf1..2f523cddab 100644 --- a/.github/actions/conditional/action.yml +++ b/.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 diff --git a/.github/actions/conditional/conditions b/.github/actions/conditional/conditions index d63a9c7aaa..e5f85ed084 100644 --- a/.github/actions/conditional/conditions +++ b/.github/actions/conditional/conditions @@ -13,6 +13,8 @@ */src/test/ ci operator pom.xml ci operator +docs/guides/ docs + js/ js *.java codeql-java diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000000..953ce8830a --- /dev/null +++ b/.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 }} diff --git a/docs/guides/src/main/.asciidoctorconfig b/docs/guides/.asciidoctorconfig similarity index 100% rename from docs/guides/src/main/.asciidoctorconfig rename to docs/guides/.asciidoctorconfig diff --git a/docs/guides/src/GENERATE-DOCS.md b/docs/guides/GENERATE-DOCS.md similarity index 77% rename from docs/guides/src/GENERATE-DOCS.md rename to docs/guides/GENERATE-DOCS.md index 28d0d7f3fb..0a9e730a5c 100644 --- a/docs/guides/src/GENERATE-DOCS.md +++ b/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//index.html`: all guides in a single html file generated with asciidoc maven plugins. +- `docs/guides/target/generated-docs//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. \ No newline at end of file diff --git a/docs/guides/src/main/getting-started/getting-started-docker.adoc b/docs/guides/getting-started/getting-started-docker.adoc similarity index 100% rename from docs/guides/src/main/getting-started/getting-started-docker.adoc rename to docs/guides/getting-started/getting-started-docker.adoc diff --git a/docs/guides/src/main/getting-started/getting-started-kube.adoc b/docs/guides/getting-started/getting-started-kube.adoc similarity index 100% rename from docs/guides/src/main/getting-started/getting-started-kube.adoc rename to docs/guides/getting-started/getting-started-kube.adoc diff --git a/docs/guides/src/main/getting-started/getting-started-openshift.adoc b/docs/guides/getting-started/getting-started-openshift.adoc similarity index 100% rename from docs/guides/src/main/getting-started/getting-started-openshift.adoc rename to docs/guides/getting-started/getting-started-openshift.adoc diff --git a/docs/guides/src/main/getting-started/getting-started-podman.adoc b/docs/guides/getting-started/getting-started-podman.adoc similarity index 100% rename from docs/guides/src/main/getting-started/getting-started-podman.adoc rename to docs/guides/getting-started/getting-started-podman.adoc diff --git a/docs/guides/src/main/getting-started/getting-started-zip.adoc b/docs/guides/getting-started/getting-started-zip.adoc similarity index 100% rename from docs/guides/src/main/getting-started/getting-started-zip.adoc rename to docs/guides/getting-started/getting-started-zip.adoc diff --git a/docs/guides/src/main/getting-started/index.adoc b/docs/guides/getting-started/index.adoc similarity index 100% rename from docs/guides/src/main/getting-started/index.adoc rename to docs/guides/getting-started/index.adoc diff --git a/docs/guides/src/main/getting-started/pinned-guides b/docs/guides/getting-started/pinned-guides similarity index 100% rename from docs/guides/src/main/getting-started/pinned-guides rename to docs/guides/getting-started/pinned-guides diff --git a/docs/guides/src/main/getting-started/templates/create-admin-localhost.adoc b/docs/guides/getting-started/templates/create-admin-localhost.adoc similarity index 100% rename from docs/guides/src/main/getting-started/templates/create-admin-localhost.adoc rename to docs/guides/getting-started/templates/create-admin-localhost.adoc diff --git a/docs/guides/src/main/getting-started/templates/first-app.adoc b/docs/guides/getting-started/templates/first-app.adoc similarity index 100% rename from docs/guides/src/main/getting-started/templates/first-app.adoc rename to docs/guides/getting-started/templates/first-app.adoc diff --git a/docs/guides/src/main/getting-started/templates/login-to-account.adoc b/docs/guides/getting-started/templates/login-to-account.adoc similarity index 100% rename from docs/guides/src/main/getting-started/templates/login-to-account.adoc rename to docs/guides/getting-started/templates/login-to-account.adoc diff --git a/docs/guides/src/main/getting-started/templates/next.adoc b/docs/guides/getting-started/templates/next.adoc similarity index 100% rename from docs/guides/src/main/getting-started/templates/next.adoc rename to docs/guides/getting-started/templates/next.adoc diff --git a/docs/guides/src/main/getting-started/templates/realm-config.adoc b/docs/guides/getting-started/templates/realm-config.adoc similarity index 100% rename from docs/guides/src/main/getting-started/templates/realm-config.adoc rename to docs/guides/getting-started/templates/realm-config.adoc diff --git a/docs/guides/src/main/getting-started/templates/start-keycloak-container.adoc b/docs/guides/getting-started/templates/start-keycloak-container.adoc similarity index 100% rename from docs/guides/src/main/getting-started/templates/start-keycloak-container.adoc rename to docs/guides/getting-started/templates/start-keycloak-container.adoc diff --git a/docs/guides/src/main/getting-started/templates/start-keycloak-localhost.adoc b/docs/guides/getting-started/templates/start-keycloak-localhost.adoc similarity index 100% rename from docs/guides/src/main/getting-started/templates/start-keycloak-localhost.adoc rename to docs/guides/getting-started/templates/start-keycloak-localhost.adoc diff --git a/docs/guides/src/main/getting-started/templates/test-app.adoc b/docs/guides/getting-started/templates/test-app.adoc similarity index 100% rename from docs/guides/src/main/getting-started/templates/test-app.adoc rename to docs/guides/getting-started/templates/test-app.adoc diff --git a/docs/guides/src/main/images/account-console.png b/docs/guides/images/account-console.png similarity index 100% rename from docs/guides/src/main/images/account-console.png rename to docs/guides/images/account-console.png diff --git a/docs/guides/src/main/images/add-client-1.png b/docs/guides/images/add-client-1.png similarity index 100% rename from docs/guides/src/main/images/add-client-1.png rename to docs/guides/images/add-client-1.png diff --git a/docs/guides/src/main/images/add-client-2.png b/docs/guides/images/add-client-2.png similarity index 100% rename from docs/guides/src/main/images/add-client-2.png rename to docs/guides/images/add-client-2.png diff --git a/docs/guides/src/main/images/add-realm.png b/docs/guides/images/add-realm.png similarity index 100% rename from docs/guides/src/main/images/add-realm.png rename to docs/guides/images/add-realm.png diff --git a/docs/guides/src/main/images/add-user.png b/docs/guides/images/add-user.png similarity index 100% rename from docs/guides/src/main/images/add-user.png rename to docs/guides/images/add-user.png diff --git a/docs/guides/src/main/images/configure-operator.jpeg b/docs/guides/images/configure-operator.jpeg similarity index 100% rename from docs/guides/src/main/images/configure-operator.jpeg rename to docs/guides/images/configure-operator.jpeg diff --git a/docs/guides/src/main/images/select-operator.jpeg b/docs/guides/images/select-operator.jpeg similarity index 100% rename from docs/guides/src/main/images/select-operator.jpeg rename to docs/guides/images/select-operator.jpeg diff --git a/docs/guides/src/main/images/set-password.png b/docs/guides/images/set-password.png similarity index 100% rename from docs/guides/src/main/images/set-password.png rename to docs/guides/images/set-password.png diff --git a/docs/guides/src/main/migration/index.adoc b/docs/guides/migration/index.adoc similarity index 100% rename from docs/guides/src/main/migration/index.adoc rename to docs/guides/migration/index.adoc diff --git a/docs/guides/src/main/migration/migrating-to-quarkus.adoc b/docs/guides/migration/migrating-to-quarkus.adoc similarity index 100% rename from docs/guides/src/main/migration/migrating-to-quarkus.adoc rename to docs/guides/migration/migrating-to-quarkus.adoc diff --git a/docs/guides/src/main/operator/advanced-configuration.adoc b/docs/guides/operator/advanced-configuration.adoc similarity index 100% rename from docs/guides/src/main/operator/advanced-configuration.adoc rename to docs/guides/operator/advanced-configuration.adoc diff --git a/docs/guides/src/main/operator/basic-deployment.adoc b/docs/guides/operator/basic-deployment.adoc similarity index 100% rename from docs/guides/src/main/operator/basic-deployment.adoc rename to docs/guides/operator/basic-deployment.adoc diff --git a/docs/guides/src/main/operator/customizing-keycloak.adoc b/docs/guides/operator/customizing-keycloak.adoc similarity index 100% rename from docs/guides/src/main/operator/customizing-keycloak.adoc rename to docs/guides/operator/customizing-keycloak.adoc diff --git a/docs/guides/src/main/operator/index.adoc b/docs/guides/operator/index.adoc similarity index 100% rename from docs/guides/src/main/operator/index.adoc rename to docs/guides/operator/index.adoc diff --git a/docs/guides/src/main/operator/installation.adoc b/docs/guides/operator/installation.adoc similarity index 100% rename from docs/guides/src/main/operator/installation.adoc rename to docs/guides/operator/installation.adoc diff --git a/docs/guides/src/main/operator/pinned-guides b/docs/guides/operator/pinned-guides similarity index 100% rename from docs/guides/src/main/operator/pinned-guides rename to docs/guides/operator/pinned-guides diff --git a/docs/guides/src/main/operator/realm-import.adoc b/docs/guides/operator/realm-import.adoc similarity index 100% rename from docs/guides/src/main/operator/realm-import.adoc rename to docs/guides/operator/realm-import.adoc diff --git a/docs/guides/pom.xml b/docs/guides/pom.xml index 70df23c321..8ba50d69c1 100644 --- a/docs/guides/pom.xml +++ b/docs/guides/pom.xml @@ -1,5 +1,5 @@ + validate copy-resources - ${basedir}/src/main/images + ${basedir}/target/generated-docs/images - ${basedir}/target/generated-guides/images + ${basedir}/images @@ -72,6 +74,9 @@ keycloak-guide + + ${project.basedir} + diff --git a/docs/guides/src/main/server/all-config.adoc b/docs/guides/server/all-config.adoc similarity index 100% rename from docs/guides/src/main/server/all-config.adoc rename to docs/guides/server/all-config.adoc diff --git a/docs/guides/src/main/server/all-provider-config.adoc b/docs/guides/server/all-provider-config.adoc similarity index 100% rename from docs/guides/src/main/server/all-provider-config.adoc rename to docs/guides/server/all-provider-config.adoc diff --git a/docs/guides/src/main/server/caching.adoc b/docs/guides/server/caching.adoc similarity index 100% rename from docs/guides/src/main/server/caching.adoc rename to docs/guides/server/caching.adoc diff --git a/docs/guides/src/main/server/configuration-metrics.adoc b/docs/guides/server/configuration-metrics.adoc similarity index 100% rename from docs/guides/src/main/server/configuration-metrics.adoc rename to docs/guides/server/configuration-metrics.adoc diff --git a/docs/guides/src/main/server/configuration-production.adoc b/docs/guides/server/configuration-production.adoc similarity index 100% rename from docs/guides/src/main/server/configuration-production.adoc rename to docs/guides/server/configuration-production.adoc diff --git a/docs/guides/src/main/server/configuration-provider.adoc b/docs/guides/server/configuration-provider.adoc similarity index 100% rename from docs/guides/src/main/server/configuration-provider.adoc rename to docs/guides/server/configuration-provider.adoc diff --git a/docs/guides/src/main/server/configuration.adoc b/docs/guides/server/configuration.adoc similarity index 100% rename from docs/guides/src/main/server/configuration.adoc rename to docs/guides/server/configuration.adoc diff --git a/docs/guides/src/main/server/containers.adoc b/docs/guides/server/containers.adoc similarity index 100% rename from docs/guides/src/main/server/containers.adoc rename to docs/guides/server/containers.adoc diff --git a/docs/guides/src/main/server/db.adoc b/docs/guides/server/db.adoc similarity index 100% rename from docs/guides/src/main/server/db.adoc rename to docs/guides/server/db.adoc diff --git a/docs/guides/src/main/server/enabletls.adoc b/docs/guides/server/enabletls.adoc similarity index 100% rename from docs/guides/src/main/server/enabletls.adoc rename to docs/guides/server/enabletls.adoc diff --git a/docs/guides/src/main/server/features.adoc b/docs/guides/server/features.adoc similarity index 100% rename from docs/guides/src/main/server/features.adoc rename to docs/guides/server/features.adoc diff --git a/docs/guides/src/main/server/fips.adoc b/docs/guides/server/fips.adoc similarity index 100% rename from docs/guides/src/main/server/fips.adoc rename to docs/guides/server/fips.adoc diff --git a/docs/guides/src/main/server/health.adoc b/docs/guides/server/health.adoc similarity index 100% rename from docs/guides/src/main/server/health.adoc rename to docs/guides/server/health.adoc diff --git a/docs/guides/src/main/server/hostname.adoc b/docs/guides/server/hostname.adoc similarity index 100% rename from docs/guides/src/main/server/hostname.adoc rename to docs/guides/server/hostname.adoc diff --git a/docs/guides/src/main/server/importExport.adoc b/docs/guides/server/importExport.adoc similarity index 100% rename from docs/guides/src/main/server/importExport.adoc rename to docs/guides/server/importExport.adoc diff --git a/docs/guides/src/main/server/index.adoc b/docs/guides/server/index.adoc similarity index 100% rename from docs/guides/src/main/server/index.adoc rename to docs/guides/server/index.adoc diff --git a/docs/guides/src/main/server/keycloak-truststore.adoc b/docs/guides/server/keycloak-truststore.adoc similarity index 100% rename from docs/guides/src/main/server/keycloak-truststore.adoc rename to docs/guides/server/keycloak-truststore.adoc diff --git a/docs/guides/src/main/server/logging.adoc b/docs/guides/server/logging.adoc similarity index 100% rename from docs/guides/src/main/server/logging.adoc rename to docs/guides/server/logging.adoc diff --git a/docs/guides/src/main/server/outgoinghttp.adoc b/docs/guides/server/outgoinghttp.adoc similarity index 100% rename from docs/guides/src/main/server/outgoinghttp.adoc rename to docs/guides/server/outgoinghttp.adoc diff --git a/docs/guides/src/main/server/pinned-guides b/docs/guides/server/pinned-guides similarity index 100% rename from docs/guides/src/main/server/pinned-guides rename to docs/guides/server/pinned-guides diff --git a/docs/guides/src/main/server/reverseproxy.adoc b/docs/guides/server/reverseproxy.adoc similarity index 100% rename from docs/guides/src/main/server/reverseproxy.adoc rename to docs/guides/server/reverseproxy.adoc diff --git a/docs/guides/src/main/server/vault.adoc b/docs/guides/server/vault.adoc similarity index 100% rename from docs/guides/src/main/server/vault.adoc rename to docs/guides/server/vault.adoc diff --git a/docs/guides/src/test/java/org/keycloak/guides/DocsBuildDebugUtil.java b/docs/guides/src/test/java/org/keycloak/guides/DocsBuildDebugUtil.java index b13b9f0ff5..1e8eb207dd 100644 --- a/docs/guides/src/test/java/org/keycloak/guides/DocsBuildDebugUtil.java +++ b/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(); - targetDir.mkdirs(); - GuideBuilder builder = new GuideBuilder(srcDir, targetDir, null); - builder.build(); - System.out.println("Guides generated to: " + targetDir.getAbsolutePath().toString()); + + for (File srcDir: usrDir.toPath().resolve("docs/guides").toFile().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 = 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()); + } } } diff --git a/docs/guides/src/main/templates/guide.adoc b/docs/guides/templates/guide.adoc similarity index 100% rename from docs/guides/src/main/templates/guide.adoc rename to docs/guides/templates/guide.adoc diff --git a/docs/guides/src/main/templates/kc.adoc b/docs/guides/templates/kc.adoc similarity index 100% rename from docs/guides/src/main/templates/kc.adoc rename to docs/guides/templates/kc.adoc diff --git a/docs/guides/src/main/templates/links.adoc b/docs/guides/templates/links.adoc similarity index 100% rename from docs/guides/src/main/templates/links.adoc rename to docs/guides/templates/links.adoc diff --git a/docs/guides/src/main/templates/options.adoc b/docs/guides/templates/options.adoc similarity index 100% rename from docs/guides/src/main/templates/options.adoc rename to docs/guides/templates/options.adoc diff --git a/docs/maven-plugin/src/main/java/org/keycloak/guides/maven/GuideMojo.java b/docs/maven-plugin/src/main/java/org/keycloak/guides/maven/GuideMojo.java index 6e27ef3a56..d6283a9ad8 100644 --- a/docs/maven-plugin/src/main/java/org/keycloak/guides/maven/GuideMojo.java +++ b/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();