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 new file mode 100644 index 0000000..3bf9396 --- /dev/null +++ b/.github/workflows/publish-javadoc.yml @@ -0,0 +1,149 @@ +name: publish-javadoc + +# Generates JavaDoc HTML for public consumption. +# +# 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: publish-javadoc-${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +jobs: + generate: + runs-on: ubuntu-latest + permissions: + contents: read + outputs: + version: ${{ steps.ver.outputs.version }} + 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) + 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 + + - name: Locate JavaDoc output + id: javadoc + run: | + if [ -d target/site/apidocs ]; then + printf 'dir=%s\n' "target/site/apidocs" >> "$GITHUB_OUTPUT" + elif [ -d target/reports/apidocs ]; then + 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: Stage site (landing + version + latest) + env: + VERSION: ${{ steps.ver.outputs.version }} + JAVADOC_DIR: ${{ steps.javadoc.outputs.dir }} + run: | + set -euo pipefail + 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: 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 + 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" + 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 ${VERSION} (${{ github.sha }})" + git push origin javadoc diff --git a/README.md b/README.md index f7504ee..30548ed 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://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) @@ -50,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 new file mode 100644 index 0000000..e005523 --- /dev/null +++ b/docs/index.html @@ -0,0 +1,169 @@ + + + + + + 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 to the + javadoc branch of this repository (no extra CI secret). + Release docs also live on javadoc.io once Central has the version. +

+ +
+ +
+

Snapshots

+

+ Dev builds: io.github.pinont:singularitylib:2.0.0-SNAPSHOT from + GitHub Packages. + maven.pinont.me is a frozen Pages archive. + 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..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 @@ -170,18 +172,20 @@ - + org.apache.maven.plugins maven-javadoc-plugin 3.7.0 + + false + false + attach-javadocs jar - - false -