Documentation Overhaul

.github/workflows/archive-docs.yml

@@ -3,19 +3,19 @@ name: Archive documentation
 on:
   release:
     types: [ published ]
-  workflow_dispatch:
 
 jobs:
   archive-docs:
-    if: "! contains(toJSON(github.event.commits.*.message), '[ci skip]')"
+    if: "!contains(toJSON(github.event.commits.*.message), '[ci skip]')"
     runs-on: ubuntu-latest
     steps:
       - name: Configure workflow
         id: configuration
         run: |
-          echo "BRANCH_NAME=${GITHUB_REF#refs/*/}" >> $GITHUB_OUTPUT
-          echo "DOCS_OUTPUT_DIR=${GITHUB_WORKSPACE}/skript-docs/docs/archives/${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
-          echo "DOCS_REPO_DIR=${GITHUB_WORKSPACE}/skript-docs" >> $GITHUB_OUTPUT
+          BRANCH_NAME="${GITHUB_REF#refs/*/}"
+          echo "BRANCH_NAME=${BRANCH_NAME}" >> $GITHUB_OUTPUT
+          echo "DOCS_OUTPUT_DIR=${GITHUB_WORKSPACE}/docs/src/assets/syntaxes/" >> $GITHUB_OUTPUT
+          echo "DOCS_REPO_DIR=${GITHUB_WORKSPACE}/docs" >> $GITHUB_OUTPUT
           echo "SKRIPT_REPO_DIR=${GITHUB_WORKSPACE}/skript" >> $GITHUB_OUTPUT
       - name: Checkout Skript
         uses: actions/checkout@v6
@@ -25,20 +25,22 @@ jobs:
       - name: Setup documentation environment
         uses: ./skript/.github/workflows/docs/setup-docs
         with:
-          docs_repo: "SkriptLang/skript-docs"
+          docs_repo: "SkriptLang/docs"
           docs_token: ${{ secrets.DOCS_TOKEN }}
       - name: Generate documentation
+        id: generate
         uses: ./skript/.github/workflows/docs/generate-docs
         with:
           docs_output_dir: ${{ steps.configuration.outputs.DOCS_OUTPUT_DIR }}
           docs_repo_dir: ${{ steps.configuration.outputs.DOCS_REPO_DIR }}
+          docs_file_name: ${{ steps.configuration.outputs.BRANCH_NAME }}
           skript_repo_dir: ${{ steps.configuration.outputs.SKRIPT_REPO_DIR }}
           is_release: true
-          generate_javadocs: true
       - name: Push archive documentation
         uses: ./skript/.github/workflows/docs/push-docs
         with:
           docs_repo_dir: ${{ steps.configuration.outputs.DOCS_REPO_DIR }}
+          docs_repo_branch: "master"
           git_name: Archive Docs Bot
           git_email: archivedocs@skriptlang.org
-          git_commit_message: "Update ${{ steps.configuration.outputs.BRANCH_NAME }} archive docs"
+          git_commit_message: "Add archive docs for ${{ steps.configuration.outputs.BRANCH_NAME }}"

.github/workflows/docs/generate-docs/action.yml

@@ -9,22 +9,16 @@ inputs:
     description: "The documentation repository directory"
     required: true
     type: string
+  docs_file_name:
+    description: "The file name of the JSON docs file to update"
+    required: true
+    type: string
   skript_repo_dir:
     description: "The Skript repository directory"
     required: true
     type: string
   is_release:
-    description: "Designates whether to generate nightly or release documentation"
-    required: false
-    default: false
-    type: boolean
-  cleanup_pattern:
-    description: "A pattern designating which files to delete when cleaning the documentation output directory"
-    required: false
-    default: "*"
-    type: string
-  generate_javadocs:
-    description: "Designates whether to generate Javadocs for this documentation"
+    description: "Designates whether to generate release or nightly documentation"
     required: false
     default: false
     type: boolean
@@ -43,65 +37,43 @@ runs:
       env:
         DOCS_OUTPUT_DIR: ${{ inputs.docs_output_dir }}
         DOCS_REPO_DIR: ${{ inputs.docs_repo_dir }}
+        DOCS_FILE_NAME: ${{ inputs.docs_file_name }}
         SKRIPT_REPO_DIR: ${{ inputs.skript_repo_dir }}
         IS_RELEASE: ${{ inputs.is_release }}
-        CLEANUP_PATTERN: ${{ inputs.cleanup_pattern }}
-        GENERATE_JAVADOCS: ${{ inputs.generate_javadocs }}
       run: |
-        replace_in_directory() {
-          find $1 -type f -exec sed -i -e "s/$2/$3/g" {} \;
-        }
-
-        get_skript_version_of_directory() {
-          jq ".source.version" "$1/docs.json"
-        }
-
-        if [ -d "${DOCS_REPO_DIR}/docs/templates" ]
-        then
-          export SKRIPT_DOCS_TEMPLATE_DIR=${DOCS_REPO_DIR}/docs/templates
-        else # compatibility for older versions
-          export SKRIPT_DOCS_TEMPLATE_DIR=${DOCS_REPO_DIR}/doc-templates
-        fi
-
-        export SKRIPT_DOCS_OUTPUT_DIR=/tmp/generated-docs
-
+        # Generate docs.json from Skript repository
+        export SKRIPT_DOCS_OUTPUT_DIR=$DOCS_OUTPUT_DIR
         cd $SKRIPT_REPO_DIR
         if [[ "${IS_RELEASE}" == "true" ]]; then
-          ./gradlew genReleaseDocs javadoc
-        elif [[ "${GENERATE_JAVADOCS}" == "true" ]]; then
-          ./gradlew genNightlyDocs javadoc
+          ./gradlew genReleaseDocs
         else
           ./gradlew genNightlyDocs
         fi
 
-        if [ -d "${DOCS_OUTPUT_DIR}" ]; then
-          if [[ "${GENERATE_JAVADOCS}" == "true" ]] || [[ "${IS_RELEASE}" == "true" ]] ; then
-              mkdir -p "${SKRIPT_DOCS_OUTPUT_DIR}/javadocs" && cp -a "./build/docs/javadoc/." "$_"
-          fi
-
-          mkdir -p "/tmp/normalized-output-docs" && cp -a "${DOCS_OUTPUT_DIR}/." "$_"
-          mkdir -p "/tmp/normalized-generated-docs" && cp -a "${SKRIPT_DOCS_OUTPUT_DIR}/." "$_"
-
-          output_skript_version=$(get_skript_version_of_directory "/tmp/normalized-output-docs")
-          generated_skript_version=$(get_skript_version_of_directory "/tmp/normalized-generated-docs")
+        # Sanitize expected existing file name
+        src_file="${DOCS_FILE_NAME//\//-}.json"
 
-          replace_in_directory "/tmp/normalized-output-docs" "${output_skript_version}" "Skript"
-          replace_in_directory "/tmp/normalized-generated-docs" "${generated_skript_version}" "Skript"
-
-          diff -qbr /tmp/normalized-output-docs /tmp/normalized-generated-docs || diff_exit_code=$?
+        # Compare generated file vs existing file for changes
+        cd $DOCS_OUTPUT_DIR
+        docs_changed=false
+        if [[ -f ${src_file} ]]; then
+          diff -qb ${src_file} Skript-docs.json || diff_exit_code=$?
           # If diff exits with exit code 1, that means there were some differences
           if [[ ${diff_exit_code} -eq 1 ]]; then
-            echo "DOCS_CHANGED=true" >> $GITHUB_OUTPUT
-            echo "Documentation has changed since last push"
-          else
-            echo "Documentation hasn't changed since last push"
+            docs_changed=true
           fi
-        else
-            echo "DOCS_CHANGED=true" >> $GITHUB_OUTPUT
-            echo "No existing documentation found"
+        else # generating these docs for the first time
+          docs_changed=true
         fi
-
-        rm -rf ${DOCS_OUTPUT_DIR}/${CLEANUP_PATTERN} || true
-        mkdir -p "${DOCS_OUTPUT_DIR}/" && cp -a "${SKRIPT_DOCS_OUTPUT_DIR}/." "$_"
 
+        # Record status
+        if [[ ${docs_changed} == "true" ]]; then
+          echo "Documentation has changed since last push"
+          echo "DOCS_CHANGED=true" >> $GITHUB_OUTPUT
+        else
+          echo "Documentation hasn't changed since last push"
+          exit
+        fi
 
+        # Replace existing file with generated file
+        mv Skript-docs.json ${src_file}

.github/workflows/docs/push-docs/action.yml

@@ -5,6 +5,10 @@ inputs:
     description: "The documentation repository directory"
     required: true
     type: string
+  docs_repo_branch:
+    description: "The branch of the documentation repository to push to"
+    required: true
+    type: string
   git_email:
     description: "The email to use for the Git commit"
     required: true
@@ -25,6 +29,7 @@ runs:
       if: success()
       env:
         DOCS_REPO_DIR: ${{ inputs.docs_repo_dir }}
+        DOCS_REPO_BRANCH: ${{ inputs.docs_repo_branch }}
         GIT_EMAIL: ${{ inputs.git_email }}
         GIT_NAME: ${{ inputs.git_name }}
         GIT_COMMIT_MESSAGE: ${{ inputs.git_commit_message }}
@@ -37,7 +42,7 @@ runs:
         # Attempt rebasing and pushing 5 times in case another job pushes before us
         for i in 1 2 3 4 5
         do
-          git pull --rebase -X theirs origin main
-          git push origin main && break
+          git pull --rebase -X theirs origin ${DOCS_REPO_BRANCH}
+          git push origin ${DOCS_REPO_BRANCH} && break
           sleep 5
         done

.github/workflows/docs/setup-docs/action.yml

@@ -14,14 +14,14 @@ runs:
   using: 'composite'
   steps:
     - name: Checkout documentation repository
-      uses: actions/checkout@v3
+      uses: actions/checkout@v6
       with:
         repository: ${{ inputs.docs_repo }}
-        path: skript-docs
+        path: docs
         token: ${{ inputs.docs_token }}
-    - uses: actions/setup-java@v3
+    - uses: actions/setup-java@v5
       with:
-        java-version: '21'
+        java-version: '25'
         distribution: 'adopt'
         cache: gradle
     - shell: bash

.github/workflows/javadocs.yml

@@ -0,0 +1,75 @@
+name: Generate Javadocs
+
+on:
+  release:
+    types: [ published ]
+  push:
+    branches:
+      - 'dev/feature'
+      - 'dev/patch'
+      - 'feature/**'
+    tags-ignore:
+      - '**'
+
+jobs:
+  javadocs:
+    if: "!contains(toJSON(github.event.commits.*.message), '[ci skip]')"
+    runs-on: ubuntu-latest
+    steps:
+      - name: Configure workflow
+        id: configuration
+        run: |
+          BRANCH_NAME="${GITHUB_REF#refs/*/}"
+          echo "BRANCH_NAME=${BRANCH_NAME}" >> $GITHUB_OUTPUT
+          echo "JAVADOCS_REPO_DIR=${GITHUB_WORKSPACE}/javadocs" >> $GITHUB_OUTPUT
+          echo "SKRIPT_REPO_DIR=${GITHUB_WORKSPACE}/skript" >> $GITHUB_OUTPUT
+      - name: Checkout Skript
+        uses: actions/checkout@v6
+        with:
+          submodules: recursive
+          path: skript
+      - name: Setup Java 25
+        uses: actions/setup-java@v5
+        with:
+          java-version: '25'
+          distribution: 'adopt'
+          cache: gradle
+      - shell: bash
+        run: chmod +x ./skript/gradlew
+      - name: Checkout javadocs
+        uses: actions/checkout@v6
+        with:
+          repository: "Skriptlang/javadocs"
+          path: javadocs
+          token: ${{ secrets.DOCS_TOKEN }}
+      - name: Generate javadocs
+        id: generate
+        shell: bash
+        env:
+          JAVADOCS_OUTPUT_DIR: ${{ steps.configuration.outputs.JAVADOCS_REPO_DIR }}
+          SKRIPT_REPO_DIR: ${{ steps.configuration.outputs.SKRIPT_REPO_DIR }}
+          BRANCH_NAME: ${{ steps.configuration.outputs.BRANCH_NAME }}
+          IS_RELEASE: ${{ github.event_name == 'release' }}
+        run: |
+          cd "${SKRIPT_REPO_DIR}"
+          if [[ "${IS_RELEASE}" == "true" ]]; then
+            ./gradlew githubRelease javadoc
+          else
+            ./gradlew nightlyRelease javadoc
+          fi
+          loc_name="${BRANCH_NAME//\//-}"
+          dir_name="${JAVADOCS_OUTPUT_DIR}/skript/${loc_name}"
+          rm -rf "${dir_name}" || true
+          mkdir -p "${dir_name}" && cp -a "./build/docs/javadoc/." "$_"
+          if [[ "${IS_RELEASE}" == "true" ]]; then
+            cd "${JAVADOCS_OUTPUT_DIR}/skript"
+            sed -i "s/const latest.*/const latest = '${loc_name}';/" index.html
+          fi
+      - name: Push javadocs
+        uses: ./skript/.github/workflows/docs/push-docs
+        with:
+          docs_repo_dir: ${{ steps.configuration.outputs.JAVADOCS_REPO_DIR }}
+          docs_repo_branch: "main"
+          git_name: Javadocs Bot
+          git_email: javadocs@skriptlang.org
+          git_commit_message: "Add javadocs for ${{ steps.configuration.outputs.BRANCH_NAME }}"

.github/workflows/cleanup-docs.yml → .github/workflows/nightly-docs-cleanup.yml

@@ -1,7 +1,9 @@
 name: Cleanup nightly documentation
+
 on: delete
+
 jobs:
-  cleanup-nightly-docs:
+  nightly-docs-cleanup:
     if: github.event.ref_type == 'branch'
     runs-on: ubuntu-latest
     steps:
@@ -12,28 +14,26 @@ jobs:
         run: |
           BRANCH_NAME="${DELETED_BRANCH#refs/*/}"
           echo "BRANCH_NAME=${BRANCH_NAME}" >> $GITHUB_OUTPUT
-          echo "DOCS_OUTPUT_DIR=${GITHUB_WORKSPACE}/skript-docs/docs/nightly/${BRANCH_NAME}" >> $GITHUB_OUTPUT
-          echo "DOCS_REPO_DIR=${GITHUB_WORKSPACE}/skript-docs" >> $GITHUB_OUTPUT
-      - name: Checkout Skript
+          echo "DOCS_OUTPUT_DIR=${GITHUB_WORKSPACE}/docs/src/assets/syntaxes/" >> $GITHUB_OUTPUT
+      - name: Checkout docs
         uses: actions/checkout@v6
         with:
-          ref: ${{ github.event.repository.default_branch }}
-          submodules: recursive
-          path: skript
-      - name: Setup documentation environment
-        uses: ./skript/.github/workflows/docs/setup-docs
-        with:
-          docs_repo: "SkriptLang/skript-docs"
-          docs_token: ${{ secrets.DOCS_TOKEN }}
+          repository: "Skriptlang/docs"
+          path: docs
+          token: ${{ secrets.DOCS_TOKEN }}
       - name: Cleanup nightly documentation
         env:
-          DOCS_OUTPUT_DIR: ${{ steps.configuration.outputs.DOCS_OUTPUT_DIR }}
+          BRANCH_NAME: ${{ steps.configuration.outputs.BRANCH_NAME }}
+          DOCS_DIR: ${{ steps.configuration.outputs.DOCS_OUTPUT_DIR }}
         run: |
-          rm -rf ${DOCS_OUTPUT_DIR} || true
+          cd "${DOCS_DIR}"
+          src_file="${BRANCH_NAME//\//-}.json"
+          rm -rf ${src_file} || true
       - name: Push nightly documentation cleanup
         uses: ./skript/.github/workflows/docs/push-docs
         with:
           docs_repo_dir: ${{ steps.configuration.outputs.DOCS_REPO_DIR }}
+          docs_repo_branch: "master"
           git_name: Nightly Docs Bot
           git_email: nightlydocs@skriptlang.org
           git_commit_message: "Delete ${{ steps.configuration.outputs.BRANCH_NAME }} branch nightly docs"

.github/workflows/nightly-docs.yml

@@ -19,8 +19,8 @@ jobs:
         run: |
           BRANCH_NAME="${GITHUB_REF#refs/*/}"
           echo "BRANCH_NAME=${BRANCH_NAME}" >> $GITHUB_OUTPUT
-          echo "DOCS_OUTPUT_DIR=${GITHUB_WORKSPACE}/skript-docs/docs/nightly/${BRANCH_NAME}" >> $GITHUB_OUTPUT
-          echo "DOCS_REPO_DIR=${GITHUB_WORKSPACE}/skript-docs" >> $GITHUB_OUTPUT
+          echo "DOCS_OUTPUT_DIR=${GITHUB_WORKSPACE}/docs/src/assets/syntaxes/" >> $GITHUB_OUTPUT
+          echo "DOCS_REPO_DIR=${GITHUB_WORKSPACE}/docs" >> $GITHUB_OUTPUT
           echo "SKRIPT_REPO_DIR=${GITHUB_WORKSPACE}/skript" >> $GITHUB_OUTPUT
       - name: Checkout Skript
         uses: actions/checkout@v6
@@ -30,20 +30,22 @@ jobs:
       - name: Setup documentation environment
         uses: ./skript/.github/workflows/docs/setup-docs
         with:
-          docs_repo: "SkriptLang/skript-docs"
+          docs_repo: "SkriptLang/docs"
           docs_token: ${{ secrets.DOCS_TOKEN }}
       - name: Generate documentation
         id: generate
         uses: ./skript/.github/workflows/docs/generate-docs
         with:
           docs_output_dir: ${{ steps.configuration.outputs.DOCS_OUTPUT_DIR }}
           docs_repo_dir: ${{ steps.configuration.outputs.DOCS_REPO_DIR }}
+          docs_file_name: ${{ steps.configuration.outputs.BRANCH_NAME }}
           skript_repo_dir: ${{ steps.configuration.outputs.SKRIPT_REPO_DIR }}
       - name: Push nightly documentation
         if: steps.generate.outputs.DOCS_CHANGED == 'true'
         uses: ./skript/.github/workflows/docs/push-docs
         with:
           docs_repo_dir: ${{ steps.configuration.outputs.DOCS_REPO_DIR }}
+          docs_repo_branch: "master"
           git_name: Nightly Docs Bot
           git_email: nightlydocs@skriptlang.org
           git_commit_message: "Update ${{ steps.configuration.outputs.BRANCH_NAME }} branch nightly docs to ${{ github.repository }}@${{ github.sha }}"