From 72fdcda7b97231c1626125e9c82fafe2df3208c9 Mon Sep 17 00:00:00 2001 From: Pikachu920 <28607612+Pikachu920@users.noreply.github.com> Date: Mon, 4 Sep 2023 12:57:01 -0500 Subject: [PATCH] Documentation actions improvements (#5735) --------- Co-authored-by: Ayham Al Ali <20037329+AyhamAl-Ali@users.noreply.github.com> Co-authored-by: LimeGlass <16087552+TheLimeGlass@users.noreply.github.com> --- .github/workflows/cleanup-docs.yml | 39 +++++++++++ .../workflows/docs/generate-docs/action.yml | 64 ++++++++++++++++++- .github/workflows/docs/push-docs/action.yml | 14 ++-- .github/workflows/docs/setup-docs/action.yml | 1 - .github/workflows/nightly-docs.yml | 15 ++++- .github/workflows/release-docs.yml | 4 +- build.gradle | 31 ++++++--- 7 files changed, 145 insertions(+), 23 deletions(-) create mode 100644 .github/workflows/cleanup-docs.yml diff --git a/.github/workflows/cleanup-docs.yml b/.github/workflows/cleanup-docs.yml new file mode 100644 index 00000000000..750bab83213 --- /dev/null +++ b/.github/workflows/cleanup-docs.yml @@ -0,0 +1,39 @@ +name: Cleanup nightly documentation +on: delete +jobs: + cleanup-nightly-docs: + if: github.event.ref_type == 'branch' + runs-on: ubuntu-latest + steps: + - name: Configure workflow + id: configuration + env: + DELETED_BRANCH: ${{ github.event.ref }} + 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 + uses: actions/checkout@v3 + with: + ref: ${{ github.event.repository.default_branch }} + submodules: recursive + path: skript + - name: Setup documentation environment + uses: ./skript/.github/workflows/docs/setup-docs + with: + docs_deploy_key: ${{ secrets.DOCS_DEPLOY_KEY }} + docs_output_dir: ${{ steps.configuration.outputs.DOCS_OUTPUT_DIR }} + - name: Cleanup nightly documentation + env: + DOCS_OUTPUT_DIR: ${{ steps.configuration.outputs.DOCS_OUTPUT_DIR }} + run: | + rm -rf ${DOCS_OUTPUT_DIR} || true + - name: Push nightly documentation cleanup + uses: ./skript/.github/workflows/docs/push-docs + with: + docs_repo_dir: ${{ steps.configuration.outputs.DOCS_REPO_DIR }} + git_name: Nightly Docs Bot + git_email: nightlydocs@skriptlang.org + git_commit_message: "Delete ${{ steps.configuration.outputs.BRANCH_NAME }} branch nightly docs" diff --git a/.github/workflows/docs/generate-docs/action.yml b/.github/workflows/docs/generate-docs/action.yml index f84023a60df..84cc2153f86 100644 --- a/.github/workflows/docs/generate-docs/action.yml +++ b/.github/workflows/docs/generate-docs/action.yml @@ -18,24 +18,82 @@ inputs: 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 + +outputs: + DOCS_CHANGED: + description: "Whether or not the documentation has changed since the last push" + value: ${{ steps.generate.outputs.DOCS_CHANGED }} runs: using: 'composite' steps: - name: generate-docs + id: generate shell: bash env: DOCS_OUTPUT_DIR: ${{ inputs.docs_output_dir }} DOCS_REPO_DIR: ${{ inputs.docs_repo_dir }} SKRIPT_REPO_DIR: ${{ inputs.skript_repo_dir }} IS_RELEASE: ${{ inputs.is_release }} + CLEANUP_PATTERN: ${{ inputs.cleanup_pattern }} run: | - export SKRIPT_DOCS_TEMPLATE_DIR=${DOCS_REPO_DIR}/doc-templates - export SKRIPT_DOCS_OUTPUT_DIR=${DOCS_OUTPUT_DIR}/ + replace_in_directory() { + find $1 -type f -exec sed -i -e "s/$2/$3/g" {} \; + } + + # this should be replaced with a more reliable jq command, + # but it can't be right now because docs.json is actually not valid json. + get_skript_version_of_directory() { + grep skriptVersion "$1/docs.json" | cut -d\" -f 4 + } + + if [ -d "${DOCS_REPO_DIR}/docs/templates" ] + then + export SKRIPT_DOCS_TEMPLATE_DIR=${DOCS_REPO_DIR}/docs/templates + else + export SKRIPT_DOCS_TEMPLATE_DIR=${DOCS_REPO_DIR}/doc-templates + fi + + export SKRIPT_DOCS_OUTPUT_DIR=/tmp/generated-docs + cd $SKRIPT_REPO_DIR if [[ "${IS_RELEASE}" == "true" ]]; then ./gradlew genReleaseDocs releaseJavadoc else ./gradlew genNightlyDocs javadoc fi - cp -a "./build/docs/javadoc/." "${DOCS_OUTPUT_DIR}/javadocs" + + if [ -d "${DOCS_OUTPUT_DIR}" ]; then + mkdir -p "${SKRIPT_DOCS_OUTPUT_DIR}/javadocs" && cp -a "./build/docs/javadoc/." "$_" + + 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") + + 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=$? + # 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" + fi + else + echo "DOCS_CHANGED=true" >> $GITHUB_OUTPUT + echo "No existing documentation found" + fi + + rm -rf ${DOCS_OUTPUT_DIR}/${CLEANUP_PATTERN} || true + mkdir -p "${DOCS_OUTPUT_DIR}/" && cp -a "${SKRIPT_DOCS_OUTPUT_DIR}/." "$_" + + diff --git a/.github/workflows/docs/push-docs/action.yml b/.github/workflows/docs/push-docs/action.yml index bcc296a85c3..477a4c46aa4 100644 --- a/.github/workflows/docs/push-docs/action.yml +++ b/.github/workflows/docs/push-docs/action.yml @@ -1,10 +1,6 @@ -name: Generate documentation +name: Push documentation inputs: - docs_output_dir: - description: "The directory to generate the documentation into" - required: true - type: string docs_repo_dir: description: "The skript-docs repository directory" required: true @@ -38,4 +34,10 @@ runs: git config user.email "${GIT_EMAIL}" git add -A git commit -m "${GIT_COMMIT_MESSAGE}" || (echo "Nothing to push!" && exit 0) - git push origin main + # 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 + sleep 5 + done diff --git a/.github/workflows/docs/setup-docs/action.yml b/.github/workflows/docs/setup-docs/action.yml index 1feedcd8f10..cd6c6a05216 100644 --- a/.github/workflows/docs/setup-docs/action.yml +++ b/.github/workflows/docs/setup-docs/action.yml @@ -38,7 +38,6 @@ runs: CLEANUP_PATTERN: ${{ inputs.cleanup_pattern }} run: | eval `ssh-agent` - rm -rf ${DOCS_OUTPUT_DIR}/${CLEANUP_PATTERN} || true echo "$DOCS_DEPLOY_KEY" | tr -d '\r' | ssh-add - > /dev/null mkdir ~/.ssh ssh-keyscan www.github.com >> ~/.ssh/known_hosts diff --git a/.github/workflows/nightly-docs.yml b/.github/workflows/nightly-docs.yml index 2a6841c3771..782b76b9ed5 100644 --- a/.github/workflows/nightly-docs.yml +++ b/.github/workflows/nightly-docs.yml @@ -9,12 +9,20 @@ on: jobs: nightly-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 + env: + DOCS_DEPLOY_KEY: ${{ secrets.DOCS_DEPLOY_KEY }} run: | + if [ -n "$DOCS_DEPLOY_KEY" ] + then + echo "DOCS_DEPLOY_KEY_PRESENT=true" >> $GITHUB_OUTPUT + else + echo "Secret 'DOCS_DEPLOY_KEY' not present. Exiting job." + fi 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 @@ -26,20 +34,23 @@ jobs: submodules: recursive path: skript - name: Setup documentation environment + if: steps.configuration.outputs.DOCS_DEPLOY_KEY_PRESENT == 'true' uses: ./skript/.github/workflows/docs/setup-docs with: docs_deploy_key: ${{ secrets.DOCS_DEPLOY_KEY }} docs_output_dir: ${{ steps.configuration.outputs.DOCS_OUTPUT_DIR }} - name: Generate documentation + id: generate + if: steps.configuration.outputs.DOCS_DEPLOY_KEY_PRESENT == 'true' 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 }} 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_output_dir: ${{ steps.configuration.outputs.DOCS_OUTPUT_DIR }} docs_repo_dir: ${{ steps.configuration.outputs.DOCS_REPO_DIR }} git_name: Nightly Docs Bot git_email: nightlydocs@skriptlang.org diff --git a/.github/workflows/release-docs.yml b/.github/workflows/release-docs.yml index 9ec5a5ad257..a8ccb4000bb 100644 --- a/.github/workflows/release-docs.yml +++ b/.github/workflows/release-docs.yml @@ -26,7 +26,6 @@ jobs: with: docs_deploy_key: ${{ secrets.DOCS_DEPLOY_KEY }} docs_output_dir: ${{ steps.configuration.outputs.DOCS_OUTPUT_DIR }} - cleanup_pattern: "!(nightly|archives)" - name: Generate documentation uses: ./skript/.github/workflows/docs/generate-docs with: @@ -34,6 +33,7 @@ jobs: docs_repo_dir: ${{ steps.configuration.outputs.DOCS_REPO_DIR }} skript_repo_dir: ${{ steps.configuration.outputs.SKRIPT_REPO_DIR }} is_release: true + cleanup_pattern: "!(nightly|archives|templates)" - name: Push release documentation uses: ./skript/.github/workflows/docs/push-docs with: @@ -68,14 +68,12 @@ jobs: - name: Generate documentation 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 }} skript_repo_dir: ${{ steps.configuration.outputs.SKRIPT_REPO_DIR }} is_release: true - name: Push archive documentation uses: ./skript/.github/workflows/docs/push-docs with: - docs_output_dir: ${{ steps.configuration.outputs.DOCS_OUTPUT_DIR }} docs_repo_dir: ${{ steps.configuration.outputs.DOCS_REPO_DIR }} git_name: Archive Docs Bot git_email: archivedocs@skriptlang.org diff --git a/build.gradle b/build.gradle index 5920cb95ac8..9a525ff1e1d 100644 --- a/build.gradle +++ b/build.gradle @@ -149,14 +149,6 @@ license { exclude('**/*.json') // JSON files do not have headers } -javadoc { - source = sourceSets.main.allJava - classpath = configurations.compileClasspath - options.encoding = 'UTF-8' - // currently our javadoc has a lot of errors, so we need to suppress the linter - options.addStringOption('Xdoclint:none', '-quiet') -} - task releaseJavadoc(type: Javadoc) { title = project.property('version') source = sourceSets.main.allJava @@ -394,3 +386,26 @@ task nightlyRelease(type: ShadowJar) { ) } } + +javadoc { + dependsOn nightlyResources + + source = sourceSets.main.allJava + + exclude("ch/njol/skript/conditions/**") + exclude("ch/njol/skript/expressions/**") + exclude("ch/njol/skript/effects/**") + exclude("ch/njol/skript/events/**") + exclude("ch/njol/skript/sections/**") + exclude("ch/njol/skript/structures/**") + exclude("ch/njol/skript/lang/function/EffFunctionCall.java") + exclude("ch/njol/skript/lang/function/ExprFunctionCall.java") + exclude("ch/njol/skript/hooks/**") + exclude("ch/njol/skript/test/**") + + classpath = configurations.compileClasspath + sourceSets.main.output + options.encoding = 'UTF-8' + // currently our javadoc has a lot of errors, so we need to suppress the linter + options.addStringOption('Xdoclint:none', '-quiet') +} +