build-docs.py

build-docs.py builds the complete Apache Juneau documentation, including both Docusaurus documentation and Maven-generated Javadocs. This script replicates the documentation generation steps from the GitHub Actions workflow, allowing you to build and test the documentation locally.

What It Does

The script performs the following steps:

1. Installs npm dependencies - Runs npm ci in the juneau-docs directory
2. Compiles Java modules - Runs mvn clean install -DskipTests to build all modules
3. Generates Maven site - Runs mvn site -DskipTests to generate the Maven project site (includes aggregate javadocs)
4. Copies current javadocs - Copies generated javadocs to juneau-docs/static/javadocs/<current-release>/
5. Updates javadocs index - Updates releases.json with version information
6. Copies Maven site - Copies the generated site to juneau-docs/static/site/ (Docusaurus will copy to build)
7. Builds Docusaurus - Runs npm run build to generate the static Docusaurus site (copies static/ to build/)
8. Copies .asf.yaml - Copies the ASF configuration file to the build directory
9. Verifies apidocs - Checks that the javadocs were successfully generated
10. Checks topic links - Validates all documentation links

Usage

Build all documentation

cd /path/to/juneau
python3 scripts/build-docs.py

This will build both the Docusaurus documentation and the Maven site with javadocs.

Skip specific steps

You can skip individual steps if you only need to rebuild part of the documentation:

# Skip npm steps (useful if you only changed Java code)
python3 scripts/build-docs.py --skip-npm

# Skip Maven steps (useful if you only changed Docusaurus docs)
python3 scripts/build-docs.py --skip-maven

# Skip copying step (useful for testing without updating build directory)
python3 scripts/build-docs.py --skip-copy

# Build for staging (sets SITE_URL for staging environment)
python3 scripts/build-docs.py --staging

Command-Line Options

• --skip-npm - Skip npm install and Docusaurus build
• --skip-maven - Skip Maven compilation and site generation
• --skip-copy - Skip copying Maven site to static directory
• --staging - Build for staging environment (sets SITE_URL)

Output Location

After successful execution, the documentation will be available in:

• Docusaurus docs: juneau-docs/build/
• Maven site: juneau-docs/build/site/
• Javadocs: juneau-docs/build/javadocs/ (versioned, copied from static/javadocs) and juneau-docs/build/site/apidocs/ (current)
• Javadocs index: juneau-docs/build/javadocs/index.html (dynamically loads from releases.json)

Requirements

• Python 3.6 or higher
• No external Python dependencies (uses only standard library)
• Node.js 18+ and npm
• Maven 3.6+ and Java 17+

Notes

• The script automatically skips tests (-DskipTests) to speed up the build
• All commands are run from the project root directory
• The script will exit immediately if any command fails (unless using --skip-* options)
• The build directory (juneau-docs/build/) will be created if it doesn't exist
• Existing site contents will be replaced when copying

Build Order

The script copies Maven site to static/site/ and updates javadocs in static/javadocs/ before building Docusaurus. Docusaurus automatically copies everything from the static/ directory to the build/ directory during the build process, so the files are available when Docusaurus processes links, preventing broken link warnings.

Integration with CI/CD

This script is used by the documentation release scripts:

• release-docs-stage.py - Calls build-docs.py --staging to build for staging
• release-docs.py - Promotes already-built documentation from staging to production