docs: publish Javadoc as part of the User Guide (#31)
diff --git a/.gitignore b/.gitignore
index 009119e..719a2a4 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,4 +8,5 @@
.claude
docs/superpowers
docs/build/
+docs/source/_extra/
docs/venv/
diff --git a/docs/README.md b/docs/README.md
index 83c5f37..64158cb 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -24,8 +24,11 @@
## Build
-Building the docs requires Python 3.9 or newer. A virtual environment under
-`docs/venv/` is the recommended workflow.
+Building the docs requires Python 3.9 or newer and a working `./mvnw` at the
+repo root (the build runs `./mvnw javadoc:javadoc` to generate the API
+reference, which also needs JDK 17 and one-time network access to fetch
+upstream `.proto` files). A virtual environment under `docs/venv/` is the
+recommended workflow.
```sh
cd docs
diff --git a/docs/build.sh b/docs/build.sh
index c487a09..bda4046 100755
--- a/docs/build.sh
+++ b/docs/build.sh
@@ -22,6 +22,14 @@
cd "$(dirname "$0")"
rm -rf build
+rm -rf source/_extra
+
+# Generate Javadoc from the repo root. javadoc:javadoc triggers
+# generate-sources, which fetches upstream protos via wget.
+(cd .. && ./mvnw -q -DskipTests javadoc:javadoc)
+
+mkdir -p source/_extra
+cp -R ../target/reports/apidocs source/_extra/api
if [ -d venv ]; then
# shellcheck disable=SC1091
diff --git a/docs/source/conf.py b/docs/source/conf.py
index cf86b40..9566303 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -32,7 +32,7 @@
}
templates_path = ["_templates"]
-exclude_patterns = []
+exclude_patterns = ["_extra"]
html_theme = "pydata_sphinx_theme"
html_theme_options = {
@@ -48,6 +48,7 @@
}
html_static_path = ["_static"]
+html_extra_path = ["_extra"]
# Auto-generate anchor links for headings h1, h2, h3.
myst_heading_anchors = 3
diff --git a/docs/source/user-guide/api-reference.md b/docs/source/user-guide/api-reference.md
new file mode 100644
index 0000000..b31ec53
--- /dev/null
+++ b/docs/source/user-guide/api-reference.md
@@ -0,0 +1,32 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# API Reference
+
+Generated Javadoc for the public Java API lives at
+<!-- Raw HTML link: MyST resolves relative .html Markdown links as
+ cross-references, which fails sphinx-build -W. The Javadoc tree is
+ copied verbatim via html_extra_path and is unknown to Sphinx. -->
+<a href="../api/index.html"><strong>api/index.html</strong></a>.
+
+The reference covers the `org.apache.datafusion` package, including
+`SessionContext`, `SessionContextBuilder`, `DataFrame`, `CsvReadOptions`,
+`ParquetReadOptions`, and `NativeLibraryLoader`, plus the
+`org.apache.datafusion.proto` helpers. Auto-generated protobuf classes are
+intentionally excluded from the Javadoc — they are an implementation detail.
diff --git a/docs/source/user-guide/index.md b/docs/source/user-guide/index.md
index 289eafa..50e41d7 100644
--- a/docs/source/user-guide/index.md
+++ b/docs/source/user-guide/index.md
@@ -38,6 +38,7 @@
parquet
proto-plans
project-status
+api-reference
```
> Early development: no releases yet, API will change. Bug reports and
diff --git a/pom.xml b/pom.xml
index 47d5b4e..d0f612d 100644
--- a/pom.xml
+++ b/pom.xml
@@ -205,6 +205,22 @@
</execution>
</executions>
</plugin>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-javadoc-plugin</artifactId>
+ <version>3.11.2</version>
+ <configuration>
+ <source>17</source>
+ <failOnError>true</failOnError>
+ <failOnWarnings>false</failOnWarnings>
+ <doctitle>Apache DataFusion Java ${project.version}</doctitle>
+ <windowtitle>Apache DataFusion Java ${project.version}</windowtitle>
+ <links>
+ <link>https://docs.oracle.com/en/java/javase/17/docs/api/</link>
+ </links>
+ <excludePackageNames>datafusion_common:org.apache.datafusion.protobuf</excludePackageNames>
+ </configuration>
+ </plugin>
</plugins>
</build>
</project>
