This is an automated email from the ASF dual-hosted git repository.
hansva pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/hop.git
The following commit(s) were added to refs/heads/main by this push:
new 782d8d95cb Fail the docs PR build when a page has no description.
#2606 (#8957)
782d8d95cb is described below
commit 782d8d95cbbc0f62ee14e54b3504ba544ab885d2
Author: Adalennis <[email protected]>
AuthorDate: Fri Oct 16 12:52:33 2026 +0200
Fail the docs PR build when a page has no description. #2606 (#8957)
* Fail the docs PR build when a page has no description. #2606
* TEST ONLY: remove the DuckDB description to show the check failing. To be
dropped before merging.
* Report pages without a description in the docs PR comment instead of
stopping the build. #2606
* Revert "TEST ONLY: remove the DuckDB description to show the check
failing. To be dropped before merging."
This reverts commit d0b7fe535e5fc8bca32403e8d71c63c7d4de6e41.
---
.github/scripts/antora-report.mjs | 24 ++++++++++-----
.github/workflows/pr_build_docs.yml | 34 +++++++++++++++++++++-
.../ROOT/pages/hop-tools/hop-conf/hop-conf.adoc | 10 +++----
.../modules/ROOT/pages/projects/advanced.adoc | 2 +-
.../hop-conf-cloud-azure-blob-storage.adoc | 0
.../hop-conf-cloud-google-cloud-storage.adoc | 0
.../hop-conf/hop-conf-cloud-google-drive.adoc | 0
.../hop-tools/hop-conf/hop-conf-projects.adoc | 0
.../hop-tools/hop-conf/hop-conf-run-hpl-hwf.adoc | 0
9 files changed, 56 insertions(+), 14 deletions(-)
diff --git a/.github/scripts/antora-report.mjs
b/.github/scripts/antora-report.mjs
index 058095b0ac..5936a12ac6 100644
--- a/.github/scripts/antora-report.mjs
+++ b/.github/scripts/antora-report.mjs
@@ -21,19 +21,28 @@
* offending .adoc lines, a job summary and, for a pull request, the sticky
* comment that pr_docs_comment.yml posts on the PR.
*
- * node antora-report.mjs <antora.log> <report dir>
+ * node antora-report.mjs <antora.log> <report dir> [<extra log>...]
+ *
+ * Extra logs use the same JSON lines format, for problems found by checks that
+ * run outside Antora (see "Check page descriptions" in pr_build_docs.yml). An
+ * entry may carry a "title" for its annotation, the default is "Antora". A log
+ * that does not exist is skipped: Antora's own log is missing when a step
+ * before the build failed.
*
* Reads GITHUB_WORKSPACE and GITHUB_STEP_SUMMARY, plus PR_NUMBER, HEAD_REPO,
* HEAD_SHA and RUN_URL for the comment. Without PR_NUMBER no comment is
written.
*/
-import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from
'node:fs'
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync }
from 'node:fs'
import { join } from 'node:path'
-const [logFile, reportDir] = process.argv.slice(2)
+const [logFile, reportDir, ...extraLogs] = process.argv.slice(2)
const root = join(process.env.GITHUB_WORKSPACE ?? '', 'hop') + '/'
const rows = []
-for (const line of readFileSync(logFile, 'utf8').split('\n')) {
+const lines = [logFile, ...extraLogs]
+ .filter((file) => existsSync(file))
+ .flatMap((file) => readFileSync(file, 'utf8').split('\n'))
+for (const line of lines) {
if (!line.startsWith('{')) continue
let e
try {
@@ -43,6 +52,7 @@ for (const line of readFileSync(logFile, 'utf8').split('\n'))
{
}
rows.push({
level: e.level,
+ title: e.title ?? 'Antora',
file: e.file?.path?.replace(root, '') ?? '',
line: e.file?.line ?? '',
msg: e.msg,
@@ -55,7 +65,7 @@ const warnings = rows.filter((r) => r.level === 'warn')
// docs still carry ~150 pre-existing warnings.
for (const r of errors) {
const where = r.file ? `file=${r.file},${r.line ? `line=${r.line},` : ''}` :
''
- console.log(`::error ${where}title=Antora::${r.msg}`)
+ console.log(`::error ${where}title=${r.title}::${r.msg}`)
}
const cell = (s) => String(s).replace(/\|/g, '\\|').replace(/\n/g, ' ')
@@ -71,7 +81,7 @@ const table = (list, name) =>
: '_none_'
const summary = [
- '## Antora build',
+ '## Documentation build',
`${errors.length} error(s), ${warnings.length} warning(s)`,
'',
'### Errors',
@@ -103,7 +113,7 @@ const body = [
? `### :x: Documentation build failed with ${errors.length} error(s)`
: '### :white_check_mark: Documentation build passed',
'',
- `Antora build of the manuals at ${HEAD_SHA.slice(0, 7)}: ` +
+ `Documentation build of the manuals at ${HEAD_SHA.slice(0, 7)}: ` +
`${errors.length} error(s), ${warnings.length} warning(s) — [run
log](${RUN_URL})`,
...(errors.length ? ['', table(errors, linked)] : []),
...(warnings.length
diff --git a/.github/workflows/pr_build_docs.yml
b/.github/workflows/pr_build_docs.yml
index 874b53d972..51b89b54fb 100644
--- a/.github/workflows/pr_build_docs.yml
+++ b/.github/workflows/pr_build_docs.yml
@@ -89,6 +89,26 @@ jobs:
exit 1
fi
+ # Antora turns a page's :description: into its meta description, the
+ # summary search engines and the site search show. Every published page
+ # needs one. Files under pages/snippets are only included by other pages,
+ # so they don't.
+ #
+ # A page without one doesn't stop the job: it is written to checks.log in
+ # the format of Antora's JSON log, so "Report problems" lists it in the
PR
+ # comment along with the Antora errors, and "Fail on documentation
checks"
+ # fails the job at the end.
+ - name: Check page descriptions
+ working-directory: hop
+ run: |
+ touch "$RUNNER_TEMP/checks.log"
+ find docs -path '*/modules/ROOT/pages/*' -name '*.adoc' -not -path
'*/pages/snippets/*' \
+ -exec grep -L '^:description:' {} + | sort | while read -r file;
do
+ printf '{"level":"error","title":"Page
description","file":{"path":"%s","line":1},"msg":"%s"}\n' \
+ "$PWD/$file" \
+ "Page without a description. Add a :description: line to its
header with a one-sentence summary of the page."
+ done >> "$RUNNER_TEMP/checks.log"
+
- name: Check out the website build
uses: actions/checkout@v7
with:
@@ -154,7 +174,9 @@ jobs:
HEAD_REPO: ${{ github.event.pull_request.head.repo.full_name }}
HEAD_SHA: ${{ github.event.pull_request.head.sha }}
RUN_URL: ${{ github.server_url }}/${{ github.repository
}}/actions/runs/${{ github.run_id }}
- run: node "$GITHUB_WORKSPACE/hop/.github/scripts/antora-report.mjs"
antora.log "$GITHUB_WORKSPACE/report"
+ run: >-
+ node "$GITHUB_WORKSPACE/hop/.github/scripts/antora-report.mjs"
+ antora.log "$GITHUB_WORKSPACE/report" "$RUNNER_TEMP/checks.log"
- name: Hand the report to the comment workflow
if: ${{ !cancelled() && github.event_name == 'pull_request' }}
@@ -172,3 +194,13 @@ jobs:
path: site
retention-days: 7
if-no-files-found: ignore
+
+ # Last, so the problems found by the checks above are in the PR comment
+ # before the job fails on them.
+ - name: Fail on documentation checks
+ if: ${{ !cancelled() }}
+ run: |
+ if [ -s "$RUNNER_TEMP/checks.log" ]; then
+ echo "::error::$(wc -l < "$RUNNER_TEMP/checks.log" | tr -d ' ')
problem(s) found by the documentation checks, listed in the PR comment and the
job summary."
+ exit 1
+ fi
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/hop-tools/hop-conf/hop-conf.adoc
b/docs/hop-user-manual/modules/ROOT/pages/hop-tools/hop-conf/hop-conf.adoc
index 8389dd6230..abfa0acdb0 100644
--- a/docs/hop-user-manual/modules/ROOT/pages/hop-tools/hop-conf/hop-conf.adoc
+++ b/docs/hop-user-manual/modules/ROOT/pages/hop-tools/hop-conf/hop-conf.adoc
@@ -302,7 +302,7 @@ Result:
== Project Usage and Configuration
-include::hop-conf-projects.adoc[]
+include::../../snippets/hop-tools/hop-conf/hop-conf-projects.adoc[]
== Graph database connections
@@ -368,7 +368,7 @@ The capabilities are listed in
xref:metadata-types/graphs/graph-database-connect
== Running Workflows and Pipelines
-include::hop-conf-run-hpl-hwf.adoc[]
+include::../../snippets/hop-tools/hop-conf/hop-conf-run-hpl-hwf.adoc[]
== Cloud Storage Configuration
@@ -382,7 +382,7 @@ N/A
Set the account, block increment size for new files and your Azure key
-include::hop-conf-cloud-azure-blob-storage.adoc[]
+include::../../snippets/hop-tools/hop-conf/hop-conf-cloud-azure-blob-storage.adoc[]
=== Google
@@ -390,11 +390,11 @@ include::hop-conf-cloud-azure-blob-storage.adoc[]
Set the path to your Google Cloud service account JSON key file
-include::hop-conf-cloud-google-cloud-storage.adoc[]
+include::../../snippets/hop-tools/hop-conf/hop-conf-cloud-google-cloud-storage.adoc[]
==== Google Drive
Set the path to your Google Drive credentials JSON file or Google Drive tokens
folder.
-include::hop-conf-cloud-google-drive.adoc[]
+include::../../snippets/hop-tools/hop-conf/hop-conf-cloud-google-drive.adoc[]
diff --git a/docs/hop-user-manual/modules/ROOT/pages/projects/advanced.adoc
b/docs/hop-user-manual/modules/ROOT/pages/projects/advanced.adoc
index 792558b2ca..429d732530 100644
--- a/docs/hop-user-manual/modules/ROOT/pages/projects/advanced.adoc
+++ b/docs/hop-user-manual/modules/ROOT/pages/projects/advanced.adoc
@@ -224,5 +224,5 @@ See xref:hop-tools/hop.adoc[hop],
xref:hop-run/index.adoc[hop run] and xref:hop-
In addition to the Hop Gui and configuration files, all aspects of and
operations on projects and environments can be managed through the Hop Conf
command line tool.
-include::../hop-tools/hop-conf/hop-conf-projects.adoc[]
+include::../snippets/hop-tools/hop-conf/hop-conf-projects.adoc[]
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/hop-tools/hop-conf/hop-conf-cloud-azure-blob-storage.adoc
b/docs/hop-user-manual/modules/ROOT/pages/snippets/hop-tools/hop-conf/hop-conf-cloud-azure-blob-storage.adoc
similarity index 100%
rename from
docs/hop-user-manual/modules/ROOT/pages/hop-tools/hop-conf/hop-conf-cloud-azure-blob-storage.adoc
rename to
docs/hop-user-manual/modules/ROOT/pages/snippets/hop-tools/hop-conf/hop-conf-cloud-azure-blob-storage.adoc
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/hop-tools/hop-conf/hop-conf-cloud-google-cloud-storage.adoc
b/docs/hop-user-manual/modules/ROOT/pages/snippets/hop-tools/hop-conf/hop-conf-cloud-google-cloud-storage.adoc
similarity index 100%
rename from
docs/hop-user-manual/modules/ROOT/pages/hop-tools/hop-conf/hop-conf-cloud-google-cloud-storage.adoc
rename to
docs/hop-user-manual/modules/ROOT/pages/snippets/hop-tools/hop-conf/hop-conf-cloud-google-cloud-storage.adoc
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/hop-tools/hop-conf/hop-conf-cloud-google-drive.adoc
b/docs/hop-user-manual/modules/ROOT/pages/snippets/hop-tools/hop-conf/hop-conf-cloud-google-drive.adoc
similarity index 100%
rename from
docs/hop-user-manual/modules/ROOT/pages/hop-tools/hop-conf/hop-conf-cloud-google-drive.adoc
rename to
docs/hop-user-manual/modules/ROOT/pages/snippets/hop-tools/hop-conf/hop-conf-cloud-google-drive.adoc
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/hop-tools/hop-conf/hop-conf-projects.adoc
b/docs/hop-user-manual/modules/ROOT/pages/snippets/hop-tools/hop-conf/hop-conf-projects.adoc
similarity index 100%
rename from
docs/hop-user-manual/modules/ROOT/pages/hop-tools/hop-conf/hop-conf-projects.adoc
rename to
docs/hop-user-manual/modules/ROOT/pages/snippets/hop-tools/hop-conf/hop-conf-projects.adoc
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/hop-tools/hop-conf/hop-conf-run-hpl-hwf.adoc
b/docs/hop-user-manual/modules/ROOT/pages/snippets/hop-tools/hop-conf/hop-conf-run-hpl-hwf.adoc
similarity index 100%
rename from
docs/hop-user-manual/modules/ROOT/pages/hop-tools/hop-conf/hop-conf-run-hpl-hwf.adoc
rename to
docs/hop-user-manual/modules/ROOT/pages/snippets/hop-tools/hop-conf/hop-conf-run-hpl-hwf.adoc
