docs: JavaDoc site (javadoc branch + javadoc.io) - #10
Merged
Conversation
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 <contact@pinont.me>
There was a problem hiding this comment.
🟡 Changes recommended
The new publish workflow can silently succeed when version parsing or the Pages rebuild trigger fails, which can leave the hosted docs stale without failing CI.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
Adds a public, Maven-site-hosted JavaDoc documentation site for SingularityLib by generating JavaDoc HTML in CI and publishing it into the Pinont/singularity-maven gh-pages tree under /javadoc/singularitylib/, alongside a small landing page and updated README links.
Changes:
- Add a landing page and redirect page under
docs/for the hosted JavaDoc site. - Add a new GitHub Actions workflow to build JavaDoc HTML and publish it to
Pinont/singularity-maven(gh-pages) under/javadoc/singularitylib/. - Update README and Maven Javadoc plugin configuration to align with the new docs publishing flow.
File summaries
| File | Description |
|---|---|
| README.md | Adds a docs badge and links to the hosted JavaDoc and fallback javadoc.io. |
| pom.xml | Centralizes maven-javadoc-plugin configuration for jar + HTML generation behavior. |
| docs/javadoc-root.html | Adds a lightweight redirect entry point for the /javadoc/ root. |
| docs/index.html | Adds a styled landing page with install coordinates and JavaDoc links. |
| .github/workflows/publish-javadoc.yml | New workflow to generate and publish JavaDoc HTML to the Pages-backed Maven repo. |
| .github/workflows/pages-repo.yml | Adds concurrency coordination/comments to avoid racing with JavaDoc publishing. |
Review details
- Files reviewed: 6/6 changed files
- Comments generated: 2
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+39
to
+40
| VERSION=$(mvn -q -DforceStdout help:evaluate -Dexpression=project.version) | ||
| echo "version=${VERSION}" >> "$GITHUB_OUTPUT" |
Comment on lines
+108
to
+111
| 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" |
This was referenced Sep 1, 2026
Resolve the pages-repo.yml conflict by keeping publish-public-repo retired (no singularity-maven git-push). Take main's release.yml (SONATYPE_* and the release-label gate) and the docs/examples README paragraph. Co-authored-by: Nonnipat Tangrojjanakhajorn <contact@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 <contact@pinont.me>
cursor
Bot
changed the title
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 <contact@pinont.me>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Ship public JavaDoc HTML for 2.0.0 and SNAPSHOT consumers. This repo’s GitHub Pages URL (
https://pinont.github.io/SingularityLib/) is captured by the pinont.me custom domain, so JavaDoc is not published there.After #12,
publish-public-repono longer git-pushesPinont/singularity-maven. Nont confirmed there is no usable PAT (MAVEN_REPO_TOKENis empty).maven.pinont.meis a frozen Pages archive. This PR does not resurrect that snapshot git-push and does not invent a new secret.JavaDoc host decision
mainjavadocbranch of this repo, pushed withGITHUB_TOKEN. Browse via jsDelivr or the branch tree. Also uploaded as thejavadoc-htmlworkflow artifact on every PR/mainrun.maven-javadoc-plugin(failOnErrorremains false) for Central / GitHub Packagesmaven.pinont.me/javadoc/— preferred if a PAT withcontents:writeonPinont/singularity-mavenexists. It does not. Blocker left for Nont.pinont.medomain)The
javadocbranch is populated only after merge tomain(orworkflow_dispatch). PR CI generates HTML and uploads the artifact; it does not push the branch.What changed vs the original #10 patch
main(ci: retire Pages snapshot push; use SONATYPE_* for Central #12 + docs: copy-paste examples for CommandGroup, conversations, and export #13). Conflict file:.github/workflows/pages-repo.yml— kept retired (dispatch-only no-op).release.ymltaken frommain(SONATYPE_USERNAME/SONATYPE_PASSWORD,releaselabel gate). This PR does not have areleaselabel and does not create tags.publish-javadoc.ymlno longer clones/pushessingularity-maven. It generates HTML, uploads an artifact, and (onmainonly) publishes thejavadocbranch. Version output is trimmed withprintf(Copilot review).javadocbranch. Snapshot jars: GitHub Packages is live;maven.pinont.menoted as frozen.#13docs/examples/paragraph kept.docs/index.htmlmatches that host story (copied onto thejavadocbranch as/index.html).paper-apito26.2.build.111-stable. The old range[26.2.build,)resolved to Paper26.3-pre-2and broke MockBukkit 4.116.1 (RegistryAccessMock/decorated_pot_pattern).Out of scope
releaselabel.MAVEN_REPO_TOKENwired.Verify
mvn javadoc:javadocproducestarget/site/apidocs/index.html.mvn javadoc:jarstill producessingularitylib-*-javadoc.jar.mvn test— 95 tests pass against the pinned Paper 26.2 bundle.publish-javadocgenerate only (no branch push).