ci: publish docs site to datafusion.apache.org/java/

[andygrove]

Summary

Wires the Sphinx docs site (merged in #24) into Apache's publishing infrastructure so it appears live at https://datafusion.apache.org/java/.

What changed

• .asf.yaml — appends a publish: block telling ASF infra to serve the asf-site branch under the java subdir.
• .github/workflows/docs.yaml — new workflow. Mirrors the layout used by datafusion-comet, with one addition: it also runs on pull requests as a build-only CI check, so a docs build break cannot land on main.
  • Triggers (push to main and PRs targeting main) are path-filtered to .asf.yaml, .github/workflows/docs.yaml, and docs/** so unrelated changes don't fire it.
  • Job-level if: startsWith(github.repository, 'apache/') skips on forks (matches comet).
  • Explicit workflow-level permissions: contents: write so the publish step can push to asf-site without widening the repo-level default and without affecting build.yml's contents: read scope.
  • PR runs only build (skip asf-site checkout and the publish step via if: github.event_name == 'push').
  • Push runs build, rsync HTML to asf-site, touch .nojekyll, commit, force-push as github-actions[bot].

One-time bootstrap before this can publish

The workflow assumes an asf-site branch exists. Before merging, a maintainer (or ASF infra) needs to create an orphan branch:

git switch --orphan asf-site
git commit --allow-empty -m "Initial asf-site branch"
git push apache asf-site

Once the branch exists, the first workflow run on main will populate it.

Notes

• The site builds with -W (warnings fail the build), so a PR with a broken cross-reference or invalid toctree will fail the check.
• PRs from forks will see this job as "skipped" rather than "passing" — that's the standard ASF pattern (also used by comet).
• The script uses git push || git push --force to handle the orphan-branch first-publish case without manual intervention.

Not in this PR

• Building Javadoc or other API reference content.
• Multi-version docs.
• A staging environment (asf-staging).
• Tag-triggered release publishing.