andygrove opened a new pull request, #31:
URL: https://github.com/apache/datafusion-java/pull/31
## Which issue does this PR close?
<!-- Closes #. -->
## Rationale for this change
The User Guide has no rendered API reference today. Readers can browse the
narrative pages but have to drop into source code to look up class and method
signatures.
## What changes are included in this PR?
Generates Javadoc at docs build time and embeds it under `/api/` in the
Sphinx output. A new "API Reference" page in the User Guide links into it.
- `pom.xml` — adds `maven-javadoc-plugin` 3.11.2, configured to exclude the
generated protobuf packages (`datafusion_common.*`,
`org.apache.datafusion.protobuf.*`) so the published reference only covers
hand-written API.
- `docs/build.sh` — invokes `./mvnw javadoc:javadoc` from the repo root and
stages `target/reports/apidocs/` into `docs/source/_extra/api/` before
`sphinx-build` runs.
- `docs/source/conf.py` — adds `html_extra_path = ["_extra"]` so Sphinx
copies the staged tree verbatim into the output, plus
`exclude_patterns = ["_extra"]` so the Javadoc-emitted `.md` files
(`legal/jquery.md`, etc.) aren't scanned as Sphinx sources under `-W`.
- `docs/source/user-guide/api-reference.md` — new page in the User Guide
toctree linking to `api/index.html`. The link is a raw HTML anchor with a
comment explaining why (MyST treats relative `.html` Markdown links as
cross-references and fails the strict build).
- `.gitignore` — ignores the new staging directory.
- `docs/README.md` — documents the new JDK + first-run network requirement
for the docs build.
## Are these changes tested?
The docs build itself is the verification. `./docs/build.sh` now produces a
single tree at `docs/build/html/` containing the existing Sphinx pages plus
`/api/index.html` and the surrounding Javadoc, and exits 0 under
`sphinx-build -W` with no warnings. The exclusion of generated protobuf
packages is verified by directory absence checks in the build output.
## Are there any user-facing changes?
Yes — the published User Guide gains an "API Reference" page and a
browsable Javadoc tree at `api/`.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
