diff --git a/.github/workflows/docs-branch-checks.yml b/.github/workflows/docs-branch-checks.yml deleted file mode 100644 index a6665bb..0000000 --- a/.github/workflows/docs-branch-checks.yml +++ /dev/null @@ -1,54 +0,0 @@ -# This is an example of the docs-pr.yml workflow available from the recrwplay org -name: "Verify Branch" - -on: - # push: - # branches: - # - dev - # schedule: - # - cron: '00 16 * * *' - workflow_dispatch: - inputs: - html: - description: 'Generate HTML' - type: boolean - required: false - default: true - links: - description: 'Check links' - type: boolean - required: false - default: true - lint: - description: 'Lint docs' - type: boolean - required: false - default: true - -jobs: - - docs-build: - if: ${{ inputs.html }} - name: Generate HTML - uses: neo4j/docs-tools/.github/workflows/reusable-docs-build.yml@main - with: - retain-artifacts: 14 - deploy-id: 0 - package-script: 'publish-verify' - cli-options: '--extension ./.docs-tools/extensions/antora/aliases-redirects' - - docs-verify: - name: Verify HTML - needs: docs-build - uses: neo4j/docs-tools/.github/workflows/reusable-docs-verify.yml@main - - docs-links: - if: ${{ inputs.links }} - name: Check links - needs: docs-build - uses: neo4j/docs-tools/.github/workflows/reusable-docs-links.yml@main - - docs-lint: - if: ${{ inputs.lint }} - name: Lint docs - uses: neo4j/docs-tools/.github/workflows/reusable-docs-vale.yml@main \ No newline at end of file diff --git a/.github/workflows/docs-deploy-surge.yml b/.github/workflows/docs-deploy-surge.yml index 3c99e26..dc6cf33 100644 --- a/.github/workflows/docs-deploy-surge.yml +++ b/.github/workflows/docs-deploy-surge.yml @@ -63,7 +63,7 @@ jobs: deployurl=$ORG-$REPO-$DEPLOYID.surge.sh echo "deploy-url=$deployurl" >> $GITHUB_OUTPUT - - uses: actions/setup-node@v3 + - uses: actions/setup-node@v4 with: node-version: lts/* @@ -80,7 +80,7 @@ jobs: # The changelog contains links to new and changed files in the deployed docs - name: Comment on PR (changelog) if: ${{ hashFiles('changelog') != '' }} - uses: marocchino/sticky-pull-request-comment@v2 + uses: marocchino/sticky-pull-request-comment@efaaab3fd41a9c3de579aba759d2552635e590fd #v2.8.0 with: number: ${{ steps.get-deploy-id.outputs.deploy-id }} recreate: true @@ -93,7 +93,7 @@ jobs: if: ${{ hashFiles('changelog') == '' }} env: DEPLOY_URL: ${{ steps.get-deploy-url.outputs.deploy-url }} - uses: marocchino/sticky-pull-request-comment@v2 + uses: marocchino/sticky-pull-request-comment@efaaab3fd41a9c3de579aba759d2552635e590fd #v2.8.0 with: number: ${{ steps.get-deploy-id.outputs.deploy-id }} header: docs-pr-changes diff --git a/.github/workflows/docs-links.yml b/.github/workflows/docs-links.yml new file mode 100644 index 0000000..53eabbf --- /dev/null +++ b/.github/workflows/docs-links.yml @@ -0,0 +1,25 @@ +# This is an example of the docs-pr.yml workflow available from the recrwplay org +name: "Check Docs Links" + +on: + push: + branches: + - dev + workflow_dispatch: + # schedule: + # - cron: '00 16 * * *' + + +jobs: + + docs-build: + name: Generate HTML + uses: ./.github/workflows/reusable-docs-build.yml + with: + retain-artifacts: 14 + deploy-id: 0 + + docs-links: + name: Check links + needs: docs-build + uses: ./.github/workflows/reusable-docs-links.yml diff --git a/.github/workflows/docs-lint.yml b/.github/workflows/docs-lint.yml new file mode 100644 index 0000000..97099f5 --- /dev/null +++ b/.github/workflows/docs-lint.yml @@ -0,0 +1,16 @@ +# Use vale to lint asciidoc +name: "Check Docs style" + +on: + push: + branches: + - dev + workflow_dispatch: + # schedule: + # - cron: '00 16 * * *' + +jobs: + + docs-lint: + name: Lint docs + uses: ./.github/workflows/reusable-docs-lint.yml diff --git a/.github/workflows/docs-pr-checks.yml b/.github/workflows/docs-pr-checks.yml index 52a9605..715a2a8 100644 --- a/.github/workflows/docs-pr-checks.yml +++ b/.github/workflows/docs-pr-checks.yml @@ -10,7 +10,7 @@ jobs: # Generate HTML docs-build-pr: - uses: neo4j/docs-tools/.github/workflows/reusable-docs-build.yml@main + uses: ./.github/workflows/reusable-docs-build.yml with: deploy-id: ${{ github.event.number }} retain-artifacts: 14 @@ -21,7 +21,7 @@ jobs: # By default, the job fails if there are errors, passes if there are warnings only. docs-verify-pr: needs: docs-build-pr - uses: neo4j/docs-tools/.github/workflows/reusable-docs-verify.yml@main + uses: ./.github/workflows/reusable-docs-verify.yml with: failOnWarnings: true @@ -38,7 +38,7 @@ jobs: steps: - name: Get file changes id: get-file-changes - uses: tj-actions/changed-files@v37 + uses: tj-actions/changed-files@cbda684547adc8c052d50711417fa61b428a9f88 # v41.1.2 with: separator: ',' files_yaml: | @@ -53,7 +53,7 @@ jobs: docs-updates-comment-pr: if: needs.docs-build-pr.outputs.pages-listed == 'success' needs: [docs-build-pr, docs-changes-pr] - uses: neo4j/docs-tools/.github/workflows/reusable-docs-pr-changes.yml@main + uses: ./.github/workflows/reusable-docs-pr-changes.yml with: pages-modified: ${{ needs.docs-changes-pr.outputs.pages-modified }} pages-added: ${{ needs.docs-changes-pr.outputs.pages-added }} @@ -63,7 +63,7 @@ jobs: docs-lint-pr: needs: docs-changes-pr if: needs.docs-changes-pr.outputs.asciidoc-files != '' - uses: neo4j/docs-tools/.github/workflows/reusable-docs-vale.yml@main + uses: ./.github/workflows/reusable-docs-lint.yml with: files: ${{ needs.docs-changes-pr.outputs.asciidoc-files }} vale-fail-on-error: true diff --git a/.github/workflows/docs-publish.yml b/.github/workflows/docs-publish.yml new file mode 100644 index 0000000..4aebea1 --- /dev/null +++ b/.github/workflows/docs-publish.yml @@ -0,0 +1,51 @@ + +name: "Publish Branch" + +on: + push: + branches: + - 'dev' + workflow_dispatch: + # schedule: + # - cron: '00 16 * * *' + +jobs: + + docs-build: + name: Generate HTML + uses: ./.github/workflows/reusable-docs-build.yml + with: + retain-artifacts: 14 + deploy-id: 0 + package-script: 'publish-verify' + cli-options: '--extension ./.docs-tools/extensions/antora/aliases-redirects' + + docs-verify: + name: Verify HTML + needs: docs-build + uses: ./.github/workflows/reusable-docs-verify.yml + with: + failOnWarnings: true + + trigger-publish: + needs: docs-verify + runs-on: ubuntu-latest + + steps: + - name: Trigger Publish + uses: peter-evans/repository-dispatch@bf47d102fdb849e755b0b0023ea3e81a44b6f570 # v2.1.2 + with: + token: ${{ secrets.DISPATCH_TOKEN }} + repository: neo4j/docs-publish + event-type: docs-tools + client-payload: |- + { + "org": "${{ github.repository_owner }}", + "repo": "${{ github.event.repository.name }}", + "run_id": "${{ github.run_id }}", + "branch": "${{ github.ref_name }}", + "publish_env": "dev", + "docsets": [ + "docs-tools" + ] + } diff --git a/.github/workflows/docs-published-links.yml b/.github/workflows/docs-published-links.yml new file mode 100644 index 0000000..f56928a --- /dev/null +++ b/.github/workflows/docs-published-links.yml @@ -0,0 +1,72 @@ +name: Check links on neo4j.com + +on: + workflow_call: + inputs: + docs-path: + description: 'The path to the docs to check' + type: string + default: 'https://neo4j.com/docs' + docset: + description: 'The doc set to check' + type: string + default: 'operations-manual' + skipfile: + description: 'The path to the skipfile' + type: string + default: '.docs-tools/link-checker/ignore-links.txt' + retain-artifacts: + description: 'The number of days to retain artifacts' + type: number + default: 7 + workflow_dispatch: + inputs: + docs-path: + description: 'The path to the docs to check' + type: string + default: 'https://neo4j.com/docs' + docset: + description: 'The doc set to check' + type: string + default: 'operations-manual' + skipfile: + description: 'The path to the skipfile' + type: string + default: '.docs-tools/link-checker/ignore-links.txt' + retain-artifacts: + description: 'The number of days to retain artifacts' + type: number + default: 7 + +jobs: + check-links: + runs-on: ubuntu-latest + + env: + DOCS_PATH: ${{ inputs.docs-path }} + DOCSET: ${{ inputs.docset }} + SKIPFILE: ${{ inputs.skipfile }} + + steps: + + - name: Checkout tools repo + uses: actions/checkout@v4 + with: + repository: neo4j/docs-tools + ref: dev + sparse-checkout: | + link-checker + path: .docs-tools + + - name: Use Node.js 16 + uses: actions/setup-node@v4 + with: + node-version: '16' + + # - name: Install link checker + # run: npm install github:recrwplay/link-checker#v0.2.0 + + - name: Run link checker + uses: filiph/linkcheck@f2c15a0be0d9c83def5df3edcc0f2d6582845f2d # 3.0.0 + with: + arguments: $DOCS_PATH/$DOCSET --skip-file $SKIPFILE -e diff --git a/.github/workflows/docs-teardown.yml b/.github/workflows/docs-teardown.yml index 1d93cba..e046595 100644 --- a/.github/workflows/docs-teardown.yml +++ b/.github/workflows/docs-teardown.yml @@ -13,7 +13,7 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/setup-node@v3 + - uses: actions/setup-node@v4 with: node-version: lts/* @@ -36,7 +36,7 @@ jobs: surge teardown $DEPLOY_URL --token "$SURGE_TOKEN" - name: Comment on PR - uses: marocchino/sticky-pull-request-comment@v2 + uses: marocchino/sticky-pull-request-comment@efaaab3fd41a9c3de579aba759d2552635e590fd #v2.8.0 with: number: ${{ github.event.pull_request.number }} header: docs-pr-changes diff --git a/.github/workflows/reusable-docs-build.yml b/.github/workflows/reusable-docs-build.yml index fd7876e..45fb565 100644 --- a/.github/workflows/reusable-docs-build.yml +++ b/.github/workflows/reusable-docs-build.yml @@ -70,7 +70,7 @@ jobs: CLI_OPTIONS: ${{ inputs.cli-options }} steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - name: Checkout tools repo uses: actions/checkout@v4 @@ -82,7 +82,7 @@ jobs: path: .docs-tools - name: Use Node.js 16 - uses: actions/setup-node@v3 + uses: actions/setup-node@v4 with: node-version: '16' @@ -96,14 +96,14 @@ jobs: run: echo $DEPLOY_ID > ./build/deployid - name: Upload HTML artifact - uses: actions/upload-artifact@v3 + uses: actions/upload-artifact@v4 with: name: docs path: build/ retention-days: ${{ inputs.retain-artifacts }} - name: Upload Log artifact - uses: actions/upload-artifact@v3 + uses: actions/upload-artifact@v4 with: name: antora-log path: build/log @@ -112,7 +112,7 @@ jobs: - name: Upload Page List artifact id: page-list-artifact if: ${{ inputs.pageList }} - uses: actions/upload-artifact@v3 + uses: actions/upload-artifact@v4 with: name: page-list path: build/site/.meta/pageList diff --git a/.github/workflows/reusable-docs-links.yml b/.github/workflows/reusable-docs-links.yml new file mode 100644 index 0000000..b5b1360 --- /dev/null +++ b/.github/workflows/reusable-docs-links.yml @@ -0,0 +1,89 @@ +name: Check links + +on: + workflow_call: + inputs: + docs-path: + description: 'The path to the docs to check' + type: string + default: 'build/site' + skipfile: + description: 'The path to the skipfile' + type: string + default: '.docs-tools/link-checker/ignore-links.txt' + retain-artifacts: + description: 'The number of days to retain artifacts' + type: number + default: 7 + workflow_dispatch: + inputs: + docs-path: + description: 'The path to the docs to check' + type: string + default: 'build/site' + skipfile: + description: 'The path to the skipfile' + type: string + default: '.docs-tools/link-checker/ignore-links.txt' + retain-artifacts: + description: 'The number of days to retain artifacts' + type: number + default: 7 + +jobs: + check-links: + runs-on: ubuntu-latest + + env: + DOCS_PATH: ${{ inputs.docs-path }} + SKIPFILE: ${{ inputs.skipfile }} + + steps: + + - name: Checkout tools repo + uses: actions/checkout@v4 + with: + repository: neo4j/docs-tools + ref: dev + sparse-checkout: | + link-checker + path: .docs-tools + + - name: Download HTML + uses: actions/download-artifact@v4 + with: + name: docs + path: build + + - name: Use Node.js 16 + uses: actions/setup-node@v4 + with: + node-version: '16' + + - name: Install link checker + run: npm install github:recrwplay/link-checker#v0.2.0 + + - name: Run link checker + run: | + npx link-checker $DOCS_PATH --skip-file $SKIPFILE -e |& tee link-log.txt + warncount=$(grep -e "[0-9]* warnings" -o link-log.txt | sed 's/ warnings//' ) + if [ $warncount -gt 0 ]; then + echo "::warning:: $warncount warnings" + fi + errorcount=$(grep -e "[0-9]* errors" -o link-log.txt | sed 's/ errors//' ) + if [ $errorcount -gt 0 ]; then + echo "::error:: Errors found: See the output of the Check links step for details" + exit 1 + fi + + # upload artifacts + + - name: Save log + uses: actions/upload-artifact@v4 + with: + name: linklog + path: link-log.txt + + # if errors, raise an issue in the repo and exit 1 to fail the workflow + # tbc... + # create an action. action needs authed token. attach log to issue. extract errors as issue text? diff --git a/.github/workflows/reusable-docs-lint.yml b/.github/workflows/reusable-docs-lint.yml new file mode 100644 index 0000000..f403139 --- /dev/null +++ b/.github/workflows/reusable-docs-lint.yml @@ -0,0 +1,95 @@ +# Documentation Style Guide Lint +# Uses Vale to lint documentation against the Documentation Style Guide +# Current POC uses the Google style guide as a base set of rules +# See .vale.ini for the current set of rules + +name: "Documentation Style Guide Check" + +on: + workflow_call: + inputs: + files: + description: 'The files to lint' + default: '.' + type: string + vale-config-file: + description: 'The vale ini file to use' + default: './lint/vale/.vale.ini' + type: string + use-default-rules: + description: 'Use default rules' + default: true + type: boolean + vale-fail-on-error: + description: 'Report vale errors as a failure' + default: false + type: boolean + reporter: + description: 'Where action messages are reported' + type: string + default: 'github-pr-check' + separator: + description: 'Delimiter for input files or folders' + type: string + default: '' + workflow_dispatch: + inputs: + files: + description: 'The files to lint' + default: '.' + type: string + vale-config-file: + description: 'The vale ini file to use' + default: './lint/vale/.vale.ini' + type: string + use-default-rules: + description: 'Use default rules' + default: true + type: boolean + vale-fail-on-error: + description: 'Report vale errors as a failure' + default: false + type: boolean + reporter: + description: 'Where action messages are reported' + type: string + default: 'github-pr-check' + separator: + description: 'Delimiter for input files or folders' + type: string + default: '' + +jobs: + + lint: + name: Lint with Vale + runs-on: ubuntu-latest + if: ${{ inputs.files != '[]' }} + steps: + + # Checkout the repo + - uses: actions/checkout@v4 + + # Fetch the default vale config and styles + # Checkout to ./lint + - name: download default rules + if: ${{ inputs.use-default-rules }} + uses: actions/checkout@v4 + with: + repository: neo4j/docs-tools + ref: dev + path: lint + sparse-checkout: | + vale + sparse-checkout-cone-mode: false + + # Run Vale + - uses: errata-ai/vale-action@reviewdog + with: + files: ${{ inputs.files }} + reporter: ${{ inputs.reporter }} + fail_on_error: ${{ inputs.vale-fail-on-error }} + separator: ${{ inputs.separator }} + vale_flags: "--config=${{ inputs.vale-config-file }}" + env: + GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}} diff --git a/.github/workflows/reusable-docs-pr-changes.yml b/.github/workflows/reusable-docs-pr-changes.yml index 6326341..d1aa336 100644 --- a/.github/workflows/reusable-docs-pr-changes.yml +++ b/.github/workflows/reusable-docs-pr-changes.yml @@ -34,7 +34,7 @@ jobs: - name: Get page list for PR changelog id: get-page-list - uses: actions/download-artifact@v3 + uses: actions/download-artifact@v4 with: name: page-list @@ -116,7 +116,7 @@ jobs: - name: Upload changelog if: ${{ hashFiles('changelog') != '' }} - uses: actions/upload-artifact@v3 + uses: actions/upload-artifact@v4 with: name: docs path: changelog \ No newline at end of file diff --git a/.github/workflows/reusable-docs-published-links.yml b/.github/workflows/reusable-docs-published-links.yml new file mode 100644 index 0000000..f56928a --- /dev/null +++ b/.github/workflows/reusable-docs-published-links.yml @@ -0,0 +1,72 @@ +name: Check links on neo4j.com + +on: + workflow_call: + inputs: + docs-path: + description: 'The path to the docs to check' + type: string + default: 'https://neo4j.com/docs' + docset: + description: 'The doc set to check' + type: string + default: 'operations-manual' + skipfile: + description: 'The path to the skipfile' + type: string + default: '.docs-tools/link-checker/ignore-links.txt' + retain-artifacts: + description: 'The number of days to retain artifacts' + type: number + default: 7 + workflow_dispatch: + inputs: + docs-path: + description: 'The path to the docs to check' + type: string + default: 'https://neo4j.com/docs' + docset: + description: 'The doc set to check' + type: string + default: 'operations-manual' + skipfile: + description: 'The path to the skipfile' + type: string + default: '.docs-tools/link-checker/ignore-links.txt' + retain-artifacts: + description: 'The number of days to retain artifacts' + type: number + default: 7 + +jobs: + check-links: + runs-on: ubuntu-latest + + env: + DOCS_PATH: ${{ inputs.docs-path }} + DOCSET: ${{ inputs.docset }} + SKIPFILE: ${{ inputs.skipfile }} + + steps: + + - name: Checkout tools repo + uses: actions/checkout@v4 + with: + repository: neo4j/docs-tools + ref: dev + sparse-checkout: | + link-checker + path: .docs-tools + + - name: Use Node.js 16 + uses: actions/setup-node@v4 + with: + node-version: '16' + + # - name: Install link checker + # run: npm install github:recrwplay/link-checker#v0.2.0 + + - name: Run link checker + uses: filiph/linkcheck@f2c15a0be0d9c83def5df3edcc0f2d6582845f2d # 3.0.0 + with: + arguments: $DOCS_PATH/$DOCSET --skip-file $SKIPFILE -e diff --git a/.github/workflows/reusable-docs-verify.yml b/.github/workflows/reusable-docs-verify.yml index fcb38f0..a311287 100644 --- a/.github/workflows/reusable-docs-verify.yml +++ b/.github/workflows/reusable-docs-verify.yml @@ -19,13 +19,13 @@ jobs: steps: - name: Download Antora log - uses: actions/download-artifact@v3 + uses: actions/download-artifact@v4 with: name: antora-log - name: Analyze Antora log id: antora-log-check-test - uses: recrwplay/antora-log-analyzer@f42057f7215a68108a2863ceecab212470e90cae + uses: recrwplay/antora-log-analyzer@f42057f7215a68108a2863ceecab212470e90cae # 1.0.0 with: fail-on-errors: ${{ inputs.failOnErrors }} fail-on-warnings: ${{ inputs.failOnWarnings }}