Apache DataFusion SQL Query Engine
dev: include the HTML documentation build in the local lint suite (#25586)
Kumar Ujjawal63ab2a855eea
diff --git a/.github/workflows/docs_pr.yaml b/.github/workflows/docs_pr.yamlindex 64be66f350..771e950723 100644--- a/.github/workflows/docs_pr.yaml+++ b/.github/workflows/docs_pr.yaml@@ -26,12 +26,14 @@ on:push:paths:- "docs/**"+ - "ci/scripts/check_docs_html.sh"branches:- main- branch-*pull_request:paths:- "docs/**"+ - "ci/scripts/check_docs_html.sh"# manual trigger# https://docs.github.com/en/actions/managing-workflow-runs/manually-running-a-workflowworkflow_dispatch:@@ -63,7 +65,4 @@ jobs:with:tool: [email protected]- name: Build docs html and check for warnings- run: |- set -x- cd docs- uv run --package datafusion-docs ./build.sh # fails on errors+ run: ./ci/scripts/check_docs_html.sh # fails on errorsdiff --git a/ci/scripts/check_docs_html.sh b/ci/scripts/check_docs_html.shnew file mode 100755index 0000000000..0d04afff13--- /dev/null+++ b/ci/scripts/check_docs_html.sh@@ -0,0 +1,87 @@+#!/usr/bin/env bash+#+# Licensed to the Apache Software Foundation (ASF) under one+# or more contributor license agreements. See the NOTICE file+# distributed with this work for additional information+# regarding copyright ownership. The ASF licenses this file+# to you under the Apache License, Version 2.0 (the+# "License"); you may not use this file except in compliance+# with the License. You may obtain a copy of the License at+#+# http://www.apache.org/licenses/LICENSE-2.0+#+# Unless required by applicable law or agreed to in writing,+# software distributed under the License is distributed on an+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY+# KIND, either express or implied. See the License for the+# specific language governing permissions and limitations+# under the License.++# Builds the documentation website with `docs/build.sh`, the same way the+# "Test doc build" job does. Sphinx runs with `-W`, so a warning fails the+# build.++set -euo pipefail++SCRIPT_NAME="$(basename "${BASH_SOURCE[0]}")"+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"+ROOT_DIR="$(cd "${SCRIPT_DIR}/../.." && pwd)"++usage() {+ cat >&2 <<USAGE+Usage: $0++Builds the HTML documentation with docs/build.sh and fails on any Sphinx+warning. There is no write mode.++Needs uv, cargo, cargo-depgraph, Graphviz dot, and make. See docs/README.md+for the Python and Graphviz setup.++Each build rewrites docs/build and docs/source/_static/data/deps.svg, which+Git ignores. The HTML entry point is docs/build/html/index.html.+USAGE+ exit 1+}++while [[ $# -gt 0 ]]; do+ case "$1" in+ -h|--help)+ usage+ ;;+ *)+ usage+ ;;+ esac+ shift+done++# Report every missing prerequisite in one run. This check installs nothing.+missing=0+require_tool() {+ local cmd="$1"+ local hint="$2"+ if ! command -v "$cmd" > /dev/null 2>&1; then+ echo "[${SCRIPT_NAME}] ${cmd} was not found on PATH. ${hint}" >&2+ missing=1+ fi+}++require_tool "uv" "Install uv to get Python and the documentation dependencies: https://docs.astral.sh/uv/getting-started/installation/"+require_tool "cargo" "Install the Rust toolchain with rustup: https://rustup.rs/"+require_tool "cargo-depgraph" "Install it with: cargo install cargo-depgraph --version '^1.6' --locked"+require_tool "dot" "Install Graphviz (e.g., brew install graphviz, or apt-get install graphviz)."+require_tool "make" "Install make (e.g., xcode-select --install, or apt-get install make)."++if [[ "${missing}" -ne 0 ]]; then+ exit 1+fi++cd "${ROOT_DIR}"++echo "[${SCRIPT_NAME}] Building the documentation website with docs/build.sh"++# `docs/build.sh` owns the dependency graph and Sphinx commands and moves to+# the docs directory itself.+uv run --package datafusion-docs ./docs/build.sh++echo "[${SCRIPT_NAME}] Wrote the HTML documentation to docs/build/html/index.html"diff --git a/dev/rust_lint.sh b/dev/rust_lint.shindex 74d5fc16d7..dbb6454302 100755--- a/dev/rust_lint.sh+++ b/dev/rust_lint.sh@@ -142,6 +142,7 @@ declare -a READONLY_STEPS=("ci/scripts/check_circular_dependencies.sh|false""ci/scripts/check_unused_dependencies.sh|false""ci/scripts/rust_docs.sh|false"+ "ci/scripts/check_docs_html.sh|false")for entry in "${WRITE_STEPS[@]}" "${READONLY_STEPS[@]}"; dodiff --git a/docs/source/contributor-guide/testing.md b/docs/source/contributor-guide/testing.mdindex 89dc7969b3..4ba7d9d011 100644--- a/docs/source/contributor-guide/testing.md+++ b/docs/source/contributor-guide/testing.md@@ -320,6 +320,19 @@ the README:[`dev/update_function_docs.sh`]: https://github.com/apache/datafusion/blob/main/dev/update_function_docs.sh[`ci/scripts/check_generated_docs.sh`]: https://github.com/apache/datafusion/blob/main/ci/scripts/check_generated_docs.sh+## Documentation HTML Build++[`ci/scripts/check_docs_html.sh`] builds the documentation website, the same+build the "Test doc build" job runs. Sphinx builds with `-W`, so one warning+fails the check. `./dev/rust_lint.sh` runs it. Run the script with `--help`+for the tools it needs and the files it writes.++```shell+./ci/scripts/check_docs_html.sh+```++[`ci/scripts/check_docs_html.sh`]: https://github.com/apache/datafusion/blob/main/ci/scripts/check_docs_html.sh+## Benchmarks### Criterion Benchmarks