From 329858f77de00dc4942f24c2b190a6cc3ce5d592 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Tue, 1 Sep 2026 20:07:37 +0000 Subject: [PATCH 1/3] docs: publish JavaDoc HTML to maven.pinont.me Generate API docs with javadoc:javadoc and copy them into Pinont/singularity-maven under /javadoc/singularitylib/ so they sit beside the snapshot Maven repo without using this repo's GitHub Pages (that URL is the pinont.me portfolio). Co-authored-by: Nonnipat Tangrojjanakhajorn --- .github/workflows/pages-repo.yml | 8 ++ .github/workflows/publish-javadoc.yml | 111 +++++++++++++++++ README.md | 4 +- docs/index.html | 168 ++++++++++++++++++++++++++ docs/javadoc-root.html | 12 ++ pom.xml | 10 +- 6 files changed, 308 insertions(+), 5 deletions(-) create mode 100644 .github/workflows/publish-javadoc.yml create mode 100644 docs/index.html create mode 100644 docs/javadoc-root.html diff --git a/.github/workflows/pages-repo.yml b/.github/workflows/pages-repo.yml index bfacff7..0bea977 100644 --- a/.github/workflows/pages-repo.yml +++ b/.github/workflows/pages-repo.yml @@ -5,10 +5,18 @@ on: branches: [ main, "rework/v2" ] workflow_dispatch: +# Shared with publish-javadoc.yml so Maven-layout and JavaDoc pushes to +# Pinont/singularity-maven gh-pages do not race. +concurrency: + group: singularity-maven-gh-pages + cancel-in-progress: false + jobs: deploy: # Pushes the maven repo layout to Pinont/singularity-maven (Pages-served, # anonymous reads). Accumulative: previously published versions are kept. + # JavaDoc HTML is published separately under /javadoc/ by publish-javadoc.yml + # — do not delete that tree. runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 diff --git a/.github/workflows/publish-javadoc.yml b/.github/workflows/publish-javadoc.yml new file mode 100644 index 0000000..6cf3aad --- /dev/null +++ b/.github/workflows/publish-javadoc.yml @@ -0,0 +1,111 @@ +name: publish-javadoc + +# Generates JavaDoc HTML and copies it into Pinont/singularity-maven (gh-pages), +# which is served at https://maven.pinont.me. Paths are under /javadoc/ so they +# never collide with the Maven layout (io/, com/) written by pages-repo.yml. +# +# Do not enable GitHub Pages on Pinont/SingularityLib — that URL is the +# portfolio (pinont.me), not this library. + +on: + push: + branches: [ main ] + workflow_dispatch: + +concurrency: + group: singularity-maven-gh-pages + cancel-in-progress: false + +jobs: + javadoc: + runs-on: ubuntu-latest + permissions: + contents: read + steps: + - uses: actions/checkout@v4 + + - name: Setup JDK 25 + uses: actions/setup-java@v4 + with: + distribution: temurin + java-version: '25' + + - name: Install annotation processor module + run: mvn -q install -DskipTests -f singularitylib-processor/pom.xml + + - name: Resolve project version + id: ver + run: | + VERSION=$(mvn -q -DforceStdout help:evaluate -Dexpression=project.version) + echo "version=${VERSION}" >> "$GITHUB_OUTPUT" + + - name: Generate JavaDoc HTML + run: mvn -q javadoc:javadoc -DskipTests + + - name: Locate JavaDoc output + id: javadoc + run: | + if [ -d target/site/apidocs ]; then + echo "dir=target/site/apidocs" >> "$GITHUB_OUTPUT" + elif [ -d target/reports/apidocs ]; then + echo "dir=target/reports/apidocs" >> "$GITHUB_OUTPUT" + else + echo "JavaDoc output not found under target/site or target/reports" >&2 + find target -type d -name apidocs || true + exit 1 + fi + + - name: Clone singularity-maven (gh-pages) + run: | + git clone --depth 1 --branch gh-pages \ + "https://x-access-token:${{ secrets.MAVEN_REPO_TOKEN }}@github.com/Pinont/singularity-maven.git" \ + singularity-maven-pages + + - name: Stage JavaDoc (Maven group paths untouched) + env: + VERSION: ${{ steps.ver.outputs.version }} + JAVADOC_DIR: ${{ steps.javadoc.outputs.dir }} + run: | + set -euo pipefail + ROOT="singularity-maven-pages" + DEST="${ROOT}/javadoc/singularitylib" + mkdir -p "${DEST}" + cp docs/javadoc-root.html "${ROOT}/javadoc/index.html" + cp docs/index.html "${DEST}/index.html" + rm -rf "${DEST}/${VERSION}" + mkdir -p "${DEST}/${VERSION}" + cp -R "${JAVADOC_DIR}/." "${DEST}/${VERSION}/" + # Copy, not symlink — GitHub Pages does not follow git symlinks. + rm -rf "${DEST}/latest" + mkdir -p "${DEST}/latest" + cp -R "${JAVADOC_DIR}/." "${DEST}/latest/" + touch "${ROOT}/.nojekyll" + + - name: Commit and push + run: | + set -euo pipefail + cd singularity-maven-pages + git config user.name "github-actions[bot]" + git config user.email "41898282+github-actions[bot]@users.noreply.github.com" + git add javadoc .nojekyll + if git diff --cached --quiet; then + echo "No javadoc changes" + exit 0 + fi + git commit -m "docs: javadoc singularitylib ${{ steps.ver.outputs.version }} (${{ github.sha }})" + for i in 1 2 3 4; do + git pull --rebase origin gh-pages + if git push origin gh-pages; then + exit 0 + fi + sleep $((i * 4)) + done + echo "Failed to push gh-pages after retries" >&2 + exit 1 + + - name: Trigger Pages rebuild + run: | + curl -s -X POST \ + -H "Authorization: Bearer ${{ secrets.MAVEN_REPO_TOKEN }}" \ + -H "Accept: application/vnd.github+json" \ + https://api.github.com/repos/Pinont/singularity-maven/pages/builds -o /dev/null -w "%{http_code}\n" diff --git a/README.md b/README.md index 71edf87..d2b8f66 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ # SingularityLib -[![](https://img.shields.io/github/license/pinont/singularitylib)](https://github.com/Pinont/SingularityLib/blob/main/LICENSE) [![](https://img.shields.io/maven-central/v/io.github.pinont/singularitylib)](https://central.sonatype.com/artifact/io.github.pinont/singularitylib) [![](https://github.com/Pinont/SingularityLib/actions/workflows/build.yml/badge.svg)](https://github.com/Pinont/SingularityLib/actions/workflows/build.yml) +[![](https://img.shields.io/github/license/pinont/singularitylib)](https://github.com/Pinont/SingularityLib/blob/main/LICENSE) [![](https://img.shields.io/maven-central/v/io.github.pinont/singularitylib)](https://central.sonatype.com/artifact/io.github.pinont/singularitylib) [![](https://github.com/Pinont/SingularityLib/actions/workflows/build.yml/badge.svg)](https://github.com/Pinont/SingularityLib/actions/workflows/build.yml) [![JavaDoc](https://img.shields.io/badge/docs-JavaDoc-e0a54b)](https://maven.pinont.me/javadoc/singularitylib/) + +**Docs / JavaDoc:** [maven.pinont.me/javadoc/singularitylib](https://maven.pinont.me/javadoc/singularitylib/) · [latest API](https://maven.pinont.me/javadoc/singularitylib/latest/) · [javadoc.io fallback](https://javadoc.io/doc/io.github.pinont/singularitylib/2.0.0) A fork of [ExperienceLib](https://github.com/pinont/ExperienceLib) diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 0000000..6e6c033 --- /dev/null +++ b/docs/index.html @@ -0,0 +1,168 @@ + + + + + + SingularityLib — Docs + + + + +
+

PaperMC · JDK 25 · Maven Central

+

SingularityLib

+

+ Core API library for Paper plugins: commands, config, GUI, items, entities, + compile-time auto-registration, database helpers, and Discord JDA bootstrap. +

+ +
+ Browse JavaDoc + Install (README) + Maven Central +
+ +
+

Maven Central coordinates

+

Releases are on Central — no extra repository block. Scope provided; the lib loads as its own server plugin.

+ 
<dependency>
+  <groupId>io.github.pinont</groupId>
+  <artifactId>singularitylib</artifactId>
+  <version>2.0.0</version>
+  <scope>provided</scope>
+</dependency>
+
+ +
+

JavaDoc

+

+ HTML is generated from src/main/java and published on + maven.pinont.me next to the snapshot Maven repository. +

+
    +
  • Latest from main — /javadoc/singularitylib/latest/
    • +
  • Per-version copies live under /javadoc/singularitylib/<version>/
    • +
  • Fallback: + javadoc.io (2.0.0) + (Central sync may lag) +
    • +
+
+ +
+

Snapshots

+

+ Dev builds: io.github.pinont:singularitylib:2.0.0-SNAPSHOT from + https://maven.pinont.me. + Full install notes, including the bootstrap paper-plugin.yml snippet, are in the + README. +

+
+ + +
+ + diff --git a/docs/javadoc-root.html b/docs/javadoc-root.html new file mode 100644 index 0000000..1beaa64 --- /dev/null +++ b/docs/javadoc-root.html @@ -0,0 +1,12 @@ + + + + + Singularity JavaDoc + + + + +

JavaDoc: SingularityLib

+ + diff --git a/pom.xml b/pom.xml index a3621cc..c8082f2 100644 --- a/pom.xml +++ b/pom.xml @@ -170,18 +170,20 @@ - + org.apache.maven.plugins maven-javadoc-plugin 3.7.0 + + false + false + attach-javadocs jar - - false - From 8a234e8d07949d691664c4de3948f0ed5f48e328 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Tue, 8 Sep 2026 02:46:12 +0000 Subject: [PATCH 2/3] docs: host JavaDoc on javadoc branch, not frozen maven.pinont.me MAVEN_REPO_TOKEN is empty, so do not git-push Pinont/singularity-maven. Generate HTML in CI, upload it as an artifact, and publish the javadoc branch with GITHUB_TOKEN. Point README at javadoc.io for 2.0.0 and jsDelivr for latest-from-main. Co-authored-by: Nonnipat Tangrojjanakhajorn --- .github/workflows/pages-repo.yml | 5 +- .github/workflows/publish-javadoc.yml | 140 ++++++++++++++++---------- README.md | 6 +- docs/index.html | 15 +-- 4 files changed, 105 insertions(+), 61 deletions(-) diff --git a/.github/workflows/pages-repo.yml b/.github/workflows/pages-repo.yml index 8a3aba7..f1a7726 100644 --- a/.github/workflows/pages-repo.yml +++ b/.github/workflows/pages-repo.yml @@ -3,7 +3,9 @@ name: publish-public-repo # Retired. This workflow used to git-push snapshots to Pinont/singularity-maven # (maven.pinont.me). That path is closed: # - Snapshots live on GitHub Packages (build.yml, GITHUB_TOKEN). -# - maven.pinont.me is a frozen Pages archive — do not git-push it from CI. +# - maven.pinont.me is a frozen Pages archive — do not git-push it from CI +# (no Maven layout, no JavaDoc). Public JavaDoc HTML is published by +# publish-javadoc.yml to the `javadoc` branch of this repo. # - Releases go to Maven Central via release.yml # (SONATYPE_USERNAME / SONATYPE_PASSWORD). # - Central Portal does not accept SNAPSHOT uploads. @@ -22,4 +24,5 @@ jobs: echo "publish-public-repo is retired." echo "Snapshots: GitHub Packages (build.yml)." echo "maven.pinont.me is a frozen Pages archive." + echo "JavaDoc HTML: publish-javadoc.yml -> javadoc branch." echo "Releases: Maven Central via release.yml." diff --git a/.github/workflows/publish-javadoc.yml b/.github/workflows/publish-javadoc.yml index 6cf3aad..3bf9396 100644 --- a/.github/workflows/publish-javadoc.yml +++ b/.github/workflows/publish-javadoc.yml @@ -1,26 +1,44 @@ name: publish-javadoc -# Generates JavaDoc HTML and copies it into Pinont/singularity-maven (gh-pages), -# which is served at https://maven.pinont.me. Paths are under /javadoc/ so they -# never collide with the Maven layout (io/, com/) written by pages-repo.yml. +# Generates JavaDoc HTML for public consumption. # -# Do not enable GitHub Pages on Pinont/SingularityLib — that URL is the -# portfolio (pinont.me), not this library. +# Hosting (after pages-repo retirement): there is no usable GitHub Actions +# secret for pushing to Pinont/singularity-maven. maven.pinont.me is a frozen +# Pages archive — this workflow does not git-push it and does not invent a +# MAVEN_REPO_TOKEN. GitHub Pages on this repo is also off-limits +# (pinont.github.io/SingularityLib is captured by the pinont.me domain). +# +# Instead: +# 1. Always generate HTML and upload it as a workflow artifact. +# 2. On push to main (and workflow_dispatch), publish the HTML to the +# `javadoc` branch of THIS repo with GITHUB_TOKEN (no extra secret). +# 3. maven-javadoc-plugin still attaches the javadoc jar for Central / +# GitHub Packages. Release JavaDoc is also on javadoc.io once Central +# has the version. +# +# Browse SNAPSHOT/latest: https://cdn.jsdelivr.net/gh/Pinont/SingularityLib@javadoc/ +# Tree: https://github.com/Pinont/SingularityLib/tree/javadoc +# +# To land HTML on maven.pinont.me/javadoc/ later, Nont needs a PAT with +# contents:write on Pinont/singularity-maven. Do not wire that until it exists. on: push: branches: [ main ] + pull_request: workflow_dispatch: concurrency: - group: singularity-maven-gh-pages - cancel-in-progress: false + group: publish-javadoc-${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} jobs: - javadoc: + generate: runs-on: ubuntu-latest permissions: contents: read + outputs: + version: ${{ steps.ver.outputs.version }} steps: - uses: actions/checkout@v4 @@ -37,7 +55,14 @@ jobs: id: ver run: | VERSION=$(mvn -q -DforceStdout help:evaluate -Dexpression=project.version) - echo "version=${VERSION}" >> "$GITHUB_OUTPUT" + VERSION=$(printf '%s' "${VERSION}" | tr -d '\r\n' | sed 's/[[:space:]]*$//') + case "${VERSION}" in + ''|*..*|*"/"*|*"\\"*) + echo "Refusing unusable project.version: '${VERSION}'" >&2 + exit 1 + ;; + esac + printf 'version=%s\n' "${VERSION}" >> "$GITHUB_OUTPUT" - name: Generate JavaDoc HTML run: mvn -q javadoc:javadoc -DskipTests @@ -46,66 +71,79 @@ jobs: id: javadoc run: | if [ -d target/site/apidocs ]; then - echo "dir=target/site/apidocs" >> "$GITHUB_OUTPUT" + printf 'dir=%s\n' "target/site/apidocs" >> "$GITHUB_OUTPUT" elif [ -d target/reports/apidocs ]; then - echo "dir=target/reports/apidocs" >> "$GITHUB_OUTPUT" + printf 'dir=%s\n' "target/reports/apidocs" >> "$GITHUB_OUTPUT" else echo "JavaDoc output not found under target/site or target/reports" >&2 find target -type d -name apidocs || true exit 1 fi - - name: Clone singularity-maven (gh-pages) - run: | - git clone --depth 1 --branch gh-pages \ - "https://x-access-token:${{ secrets.MAVEN_REPO_TOKEN }}@github.com/Pinont/singularity-maven.git" \ - singularity-maven-pages - - - name: Stage JavaDoc (Maven group paths untouched) + - name: Stage site (landing + version + latest) env: VERSION: ${{ steps.ver.outputs.version }} JAVADOC_DIR: ${{ steps.javadoc.outputs.dir }} run: | set -euo pipefail - ROOT="singularity-maven-pages" - DEST="${ROOT}/javadoc/singularitylib" - mkdir -p "${DEST}" - cp docs/javadoc-root.html "${ROOT}/javadoc/index.html" - cp docs/index.html "${DEST}/index.html" - rm -rf "${DEST}/${VERSION}" - mkdir -p "${DEST}/${VERSION}" - cp -R "${JAVADOC_DIR}/." "${DEST}/${VERSION}/" - # Copy, not symlink — GitHub Pages does not follow git symlinks. - rm -rf "${DEST}/latest" - mkdir -p "${DEST}/latest" - cp -R "${JAVADOC_DIR}/." "${DEST}/latest/" - touch "${ROOT}/.nojekyll" + SITE="${{ github.workspace }}/javadoc-site" + mkdir -p "${SITE}/${VERSION}" "${SITE}/latest" + cp docs/index.html "${SITE}/index.html" + cp -R "${JAVADOC_DIR}/." "${SITE}/${VERSION}/" + cp -R "${JAVADOC_DIR}/." "${SITE}/latest/" + touch "${SITE}/.nojekyll" - - name: Commit and push + - name: Upload JavaDoc HTML artifact + uses: actions/upload-artifact@v4 + with: + name: javadoc-html + path: javadoc-site + if-no-files-found: error + + publish: + # Never publish from pull requests. workflow_dispatch may run off main. + if: github.event_name == 'workflow_dispatch' || (github.event_name == 'push' && github.ref == 'refs/heads/main') + needs: generate + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - name: Download JavaDoc HTML artifact + uses: actions/download-artifact@v4 + with: + name: javadoc-html + path: javadoc-site + + - name: Publish to javadoc branch + env: + VERSION: ${{ needs.generate.outputs.version }} + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | set -euo pipefail - cd singularity-maven-pages + SITE="${{ github.workspace }}/javadoc-site" + git clone --depth 1 "https://x-access-token:${GH_TOKEN}@github.com/${{ github.repository }}.git" repo + cd repo git config user.name "github-actions[bot]" git config user.email "41898282+github-actions[bot]@users.noreply.github.com" - git add javadoc .nojekyll + if git ls-remote --exit-code --heads origin javadoc >/dev/null; then + git fetch --depth 1 origin javadoc + git checkout -B javadoc origin/javadoc + else + git checkout --orphan javadoc + git rm -rf --quiet . >/dev/null 2>&1 || true + git clean -fdx >/dev/null 2>&1 || true + fi + mkdir -p "${VERSION}" latest + cp "${SITE}/index.html" index.html + cp "${SITE}/.nojekyll" .nojekyll + rm -rf "${VERSION}" latest + mkdir -p "${VERSION}" latest + cp -R "${SITE}/${VERSION}/." "${VERSION}/" + cp -R "${SITE}/latest/." latest/ + git add -A if git diff --cached --quiet; then echo "No javadoc changes" exit 0 fi - git commit -m "docs: javadoc singularitylib ${{ steps.ver.outputs.version }} (${{ github.sha }})" - for i in 1 2 3 4; do - git pull --rebase origin gh-pages - if git push origin gh-pages; then - exit 0 - fi - sleep $((i * 4)) - done - echo "Failed to push gh-pages after retries" >&2 - exit 1 - - - name: Trigger Pages rebuild - run: | - curl -s -X POST \ - -H "Authorization: Bearer ${{ secrets.MAVEN_REPO_TOKEN }}" \ - -H "Accept: application/vnd.github+json" \ - https://api.github.com/repos/Pinont/singularity-maven/pages/builds -o /dev/null -w "%{http_code}\n" + git commit -m "docs: javadoc singularitylib ${VERSION} (${{ github.sha }})" + git push origin javadoc diff --git a/README.md b/README.md index 17b2224..30548ed 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # SingularityLib -[![](https://img.shields.io/github/license/pinont/singularitylib)](https://github.com/Pinont/SingularityLib/blob/main/LICENSE) [![](https://img.shields.io/maven-central/v/io.github.pinont/singularitylib)](https://central.sonatype.com/artifact/io.github.pinont/singularitylib) [![](https://github.com/Pinont/SingularityLib/actions/workflows/build.yml/badge.svg)](https://github.com/Pinont/SingularityLib/actions/workflows/build.yml) [![JavaDoc](https://img.shields.io/badge/docs-JavaDoc-e0a54b)](https://maven.pinont.me/javadoc/singularitylib/) +[![](https://img.shields.io/github/license/pinont/singularitylib)](https://github.com/Pinont/SingularityLib/blob/main/LICENSE) [![](https://img.shields.io/maven-central/v/io.github.pinont/singularitylib)](https://central.sonatype.com/artifact/io.github.pinont/singularitylib) [![](https://github.com/Pinont/SingularityLib/actions/workflows/build.yml/badge.svg)](https://github.com/Pinont/SingularityLib/actions/workflows/build.yml) [![JavaDoc](https://img.shields.io/badge/docs-JavaDoc-e0a54b)](https://javadoc.io/doc/io.github.pinont/singularitylib/2.0.0) -**Docs / JavaDoc:** [maven.pinont.me/javadoc/singularitylib](https://maven.pinont.me/javadoc/singularitylib/) · [latest API](https://maven.pinont.me/javadoc/singularitylib/latest/) · [javadoc.io fallback](https://javadoc.io/doc/io.github.pinont/singularitylib/2.0.0) +**Docs / JavaDoc:** [javadoc.io (2.0.0)](https://javadoc.io/doc/io.github.pinont/singularitylib/2.0.0) · [latest from `main`](https://cdn.jsdelivr.net/gh/Pinont/SingularityLib@javadoc/latest/) · [`javadoc` branch](https://github.com/Pinont/SingularityLib/tree/javadoc) A fork of [ExperienceLib](https://github.com/pinont/ExperienceLib) @@ -52,6 +52,8 @@ SingularityLib is published to **Maven Central** — no repository block needed ### Snapshots (dev/pre-release) +Live SNAPSHOT jars are published to [GitHub Packages](https://github.com/Pinont/SingularityLib/packages) (`build.yml`, `GITHUB_TOKEN`). `https://maven.pinont.me` is a frozen Pages archive and is not updated from CI. + ```xml diff --git a/docs/index.html b/docs/index.html index 6e6c033..e005523 100644 --- a/docs/index.html +++ b/docs/index.html @@ -135,15 +135,15 @@

Maven Central coordinates

JavaDoc

- HTML is generated from src/main/java and published on - maven.pinont.me next to the snapshot Maven repository. + HTML is generated from src/main/java and published to the + javadoc branch of this repository (no extra CI secret). + Release docs also live on javadoc.io once Central has the version.

    -
  • Latest from main — /javadoc/singularitylib/latest/
    • -
  • Per-version copies live under /javadoc/singularitylib/<version>/
    • -
  • Fallback: +
  • Latest from main
    • +
  • Per-version copies live alongside this page (folder named after the pom version)
    • +
  • Release: javadoc.io (2.0.0) - (Central sync may lag)
@@ -152,7 +152,8 @@

JavaDoc

Snapshots

Dev builds: io.github.pinont:singularitylib:2.0.0-SNAPSHOT from - https://maven.pinont.me. + GitHub Packages. + maven.pinont.me is a frozen Pages archive. Full install notes, including the bootstrap paper-plugin.yml snippet, are in the README.

From 05e600a9b3ba87329f467b606f1767c97019a679 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Tue, 8 Sep 2026 02:49:43 +0000 Subject: [PATCH 3/3] fix(ci): pin paper-api to 26.2.build.111-stable for MockBukkit The [26.2.build,) range resolved to 26.3-pre-2.build.0-alpha, which breaks MockBukkit 4.116.1 (RegistryAccessMock / decorated_pot_pattern). Pin to the 26.2 bundle MockBukkit was built against so tests run. Co-authored-by: Nonnipat Tangrojjanakhajorn --- pom.xml | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/pom.xml b/pom.xml index c8082f2..2788dd9 100644 --- a/pom.xml +++ b/pom.xml @@ -96,8 +96,10 @@ 25 - - [26.2.build,) + + 26.2.build.111-stable 26.2.build.7-beta