This is an automated email from the ASF dual-hosted git repository.
jamesbognar pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/juneau.git
The following commit(s) were added to refs/heads/master by this push:
new c76123021 New GitHub workflow to set up pages
c76123021 is described below
commit c761230215ad8e601cf74b9a8eea7533cfbd79c1
Author: James Bognar <[email protected]>
AuthorDate: Fri Sep 12 17:45:22 2025 -0400
New GitHub workflow to set up pages
---
.github/README-PAGES.md | 85 +++++++++++++++++++++++++++++++++++++
.github/workflows/pages.yml | 101 ++++++++++++++++++++++++++++++++++++++++++++
.gitignore | 2 +
docs/index.html | 14 ++++++
pom.xml | 4 ++
5 files changed, 206 insertions(+)
diff --git a/.github/README-PAGES.md b/.github/README-PAGES.md
new file mode 100644
index 000000000..1bd5467ce
--- /dev/null
+++ b/.github/README-PAGES.md
@@ -0,0 +1,85 @@
+<!--
+
***************************************************************************************************************************
+ * 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.
*
+
***************************************************************************************************************************
+-->
+# GitHub Pages Configuration for Juneau
+
+## Overview
+
+This repository is configured to automatically deploy documentation to GitHub
Pages from a combination of:
+- Static documentation files in `/docs`
+- Generated Javadocs from `mvn javadoc:aggregate`
+
+## How it works
+
+### Automatic Deployment
+The `pages.yml` workflow automatically deploys to GitHub Pages when:
+- Code is pushed to the `master` or `main` branch
+- Changes are made to `docs/**`, `juneau-*/**`, `pom.xml`, or the workflow file
+- The workflow is manually triggered from the Actions tab
+
+### Build Process
+1. **Environment Setup**: Sets up Java 17 and Maven with dependency caching
+2. **Build**: Compiles Juneau modules with `mvn clean compile -DskipTests`
+3. **Site Generation**:
+ - Builds the `juneau-doc` module (for custom documentation)
+ - Generates complete project site with `mvn site -DskipTests`
+ - Includes: Javadocs, test reports, dependency info, project reports
+4. **Deployment**: Uploads entire `target/site` folder to GitHub Pages
+
+### Documentation Structure
+Once deployed, the comprehensive site will be available at:
+- **Project Home**: `https://<username>.github.io/juneau/`
+- **API Documentation**: `https://<username>.github.io/juneau/apidocs/` (if
generated)
+- **Test Reports**: `https://<username>.github.io/juneau/surefire.html`
+- **Dependencies**: `https://<username>.github.io/juneau/dependencies.html`
+- **Project Reports**:
`https://<username>.github.io/juneau/project-reports.html`
+
+## Manual Setup Required
+
+After pushing this workflow, enable GitHub Pages in your repository:
+
+1. Go to **Settings** → **Pages**
+2. Under **Source**, select **GitHub Actions**
+3. The site will be available at: `https://<username>.github.io/juneau/`
+
+## Local Development
+
+To generate the complete project site locally:
+
+```bash
+# Build the project
+mvn clean compile -DskipTests
+
+# Build documentation module
+cd juneau-doc
+mvn install -DskipTests
+cd ..
+
+# Generate complete project site
+mvn site -DskipTests
+```
+
+The generated site will be available in:
+- Complete site: `target/site/index.html`
+- Project reports: `target/site/project-reports.html`
+- Dependencies: `target/site/dependencies.html`
+- Test results: `target/site/surefire.html`
+- Javadocs: `target/site/apidocs/` (if aggregate goal works)
+
+## Integration with Existing Build Scripts
+
+This GitHub Pages workflow is designed to work alongside the existing
`juneau-build-javadoc.sh` script:
+- The GitHub workflow focuses on public documentation deployment
+- The existing script handles more complex documentation generation and
website publishing
+- Both can coexist without conflicts
diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
new file mode 100644
index 000000000..9e6809bb1
--- /dev/null
+++ b/.github/workflows/pages.yml
@@ -0,0 +1,101 @@
+# 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.
+
+name: Deploy Documentation to GitHub Pages
+
+on:
+ # Runs on pushes targeting the default branch
+ push:
+ branches: [ master, main ]
+ paths:
+ - 'docs/**'
+ - 'juneau-*/**'
+ - 'pom.xml'
+ - '.github/workflows/pages.yml'
+
+ # Allows you to run this workflow manually from the Actions tab
+ workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+ contents: read
+ pages: write
+ id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the
in-progress run and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production
deployments to complete.
+concurrency:
+ group: "pages"
+ cancel-in-progress: false
+
+jobs:
+ # Build job
+ build:
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+
+ - name: Set up JDK 17
+ uses: actions/setup-java@v4
+ with:
+ java-version: '17'
+ distribution: 'temurin'
+
+ - name: Cache Maven dependencies
+ uses: actions/cache@v4
+ with:
+ path: ~/.m2
+ key: ${{ runner.os }}-m2-${{ hashFiles('**/pom.xml') }}
+ restore-keys: ${{ runner.os }}-m2
+
+ - name: Build Juneau
+ run: |
+ mvn clean compile -DskipTests
+
+ - name: Build Documentation Site
+ run: |
+ # Set up environment
+ export JUNEAU_VERSION=$(mvn help:evaluate
-Dexpression=project.version -q -DforceStdout | grep -v "WARNING")
+ echo "Building site for Juneau version: $JUNEAU_VERSION"
+
+ # Build juneau-doc module (needed for custom docs)
+ cd juneau-doc
+ mvn install -DskipTests
+ cd ..
+
+ # Generate complete project site (includes Javadocs, test reports,
etc.)
+ mvn site -DskipTests
+
+ - name: Setup Pages
+ uses: actions/configure-pages@v4
+
+ - name: Upload artifact
+ uses: actions/upload-pages-artifact@v3
+ with:
+ # Upload the complete generated site
+ path: './target/site'
+
+ # Deployment job
+ deploy:
+ environment:
+ name: github-pages
+ url: ${{ steps.deployment.outputs.page_url }}
+ runs-on: ubuntu-latest
+ needs: build
+ steps:
+ - name: Deploy to GitHub Pages
+ id: deployment
+ uses: actions/deploy-pages@v4
diff --git a/.gitignore b/.gitignore
index 6d196b241..5eed3a1ab 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,3 +5,5 @@
**/.settings/
/bin/
derby.log
+
+# Note: Maven site generation creates target/site/ (already ignored by
**/target/ above)
diff --git a/docs/index.html b/docs/index.html
index 8d26ab1c5..6b0a24c3a 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -1,4 +1,18 @@
<!DOCTYPE html>
+<!--
+
***************************************************************************************************************************
+ * 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.
*
+
***************************************************************************************************************************
+-->
<html lang="en">
<head>
<meta charset="UTF-8">
diff --git a/pom.xml b/pom.xml
index 97a140247..e6b86313b 100644
--- a/pom.xml
+++ b/pom.xml
@@ -199,6 +199,10 @@
<goals>
<goal>aggregate</goal>
</goals>
+ <configuration>
+ <!-- Override
output directory for aggregate goal -->
+
<outputDirectory>${basedir}/docs/api</outputDirectory>
+ </configuration>
</execution>
</executions>
</plugin>
