mkdoc setup and build script

Author: SiyaoIsHiding

build-doc.sh

@@ -0,0 +1,23 @@
+set -e
+# Set up python environment
+#pyenv local 3.10.1
+#pip install mkdocs mkdocs-material pip install mkdocs-awesome-pages-plugin
+
+# In some bash/zsh environments, the locale is not set correctly, which causes mkdocs to fail.
+export LC_ALL=en_US.UTF-8
+export LANG=en_US.UTF-8
+
+# Build Javadoc
+mvn clean install -DskipTests # or guava-shaded can not be found
+mvn javadoc:javadoc -pl core,query-builder,mapper-runtime
+mvn javadoc:aggregate
+
+# Copy Javadoc to manual directory
+mkdir manual/api || true
+cp -r target/site/apidocs/*  manual/api
+
+# Build manual with API references
+mkdocs build # or `mkdocs serve` to preview
+
+# Remove Javadoc from manual directory
+rm -rf manual/api

docs.yaml

@@ -0,0 +1 @@
+../README.md

manual/HOME-README.md

@@ -0,0 +1 @@
+../changelog/README.md

manual/changelog-README.md

@@ -0,0 +1 @@
+../faq/README.md

manual/faq-README.md

@@ -0,0 +1 @@
+../upgrade_guide/README.md

manual/upgrade-README.md

@@ -0,0 +1,110 @@
+site_name: Java Driver for Apache Cassandra
+site_description: Java Driver for Apache Cassandra® Documentation
+site_url: https://apache.github.io/cassandra-java-driver
+repo_url: https://github.com/apache/cassandra-java-driver
+repo_name: apache/cassandra-java-driver
+
+docs_dir: manual
+site_dir: docs
+
+theme:
+  name: material
+  palette:
+    - scheme: default
+      primary: blue
+      accent: blue
+  features:
+    - navigation.tabs
+    - navigation.sections
+    - navigation.expand
+    - navigation.top
+    - search.highlight
+    - search.share
+
+markdown_extensions:
+  - admonition
+  - codehilite
+  - pymdownx.superfences
+  - pymdownx.tabbed
+  - toc:
+      permalink: true
+
+nav:
+  - Home: HOME-README.md
+  - Manual:
+    - Overview: README.md
+    - API Conventions: api_conventions/README.md
+    - Case Sensitivity: case_sensitivity/README.md
+    - Cloud: cloud/README.md
+    - Core:
+      - Overview: core/README.md
+      - Integration: core/integration/README.md
+      - Configuration: core/configuration/README.md
+      - Authentication: core/authentication/README.md
+      - SSL: core/ssl/README.md
+      - Load Balancing: core/load_balancing/README.md
+      - Pooling: core/pooling/README.md
+      - Reconnection: core/reconnection/README.md
+      - Retries: core/retries/README.md
+      - Speculative Execution: core/speculative_execution/README.md
+      - Metrics: core/metrics/README.md
+      - Logging: core/logging/README.md
+      - Statements: core/statements/README.md
+      - Paging: core/paging/README.md
+      - Async Programming: core/async/README.md
+      - Reactive Streams: core/reactive/README.md
+      - Custom Codecs: core/custom_codecs/README.md
+      - Temporal Types: core/temporal_types/README.md
+      - Tuples: core/tuples/README.md
+      - UDTs: core/udts/README.md
+      - Compression: core/compression/README.md
+      - Address Resolution: core/address_resolution/README.md
+      - Request Tracker: core/request_tracker/README.md
+      - Throttling: core/throttling/README.md
+      - Tracing: core/tracing/README.md
+      - Performance: core/performance/README.md
+      - Metadata: core/metadata/README.md
+      - Control Connection: core/control_connection/README.md
+      - Native Protocol: core/native_protocol/README.md
+      - Non-blocking: core/non_blocking/README.md
+      - Query Timestamps: core/query_timestamps/README.md
+      - Idempotence: core/idempotence/README.md
+      - Detachable Types: core/detachable_types/README.md
+      - DSE: core/dse/README.md
+      - GraalVM: core/graalvm/README.md
+      - Shaded JAR: core/shaded_jar/README.md
+      - BOM: core/bom/README.md
+    - Query Builder:
+      - Overview: query_builder/README.md
+      - Select: query_builder/select/README.md
+      - Insert: query_builder/insert/README.md
+      - Update: query_builder/update/README.md
+      - Delete: query_builder/delete/README.md
+      - Schema: query_builder/schema/README.md
+      - Truncate: query_builder/truncate/README.md
+      - Condition: query_builder/condition/README.md
+      - Relation: query_builder/relation/README.md
+      - Term: query_builder/term/README.md
+      - Idempotence: query_builder/idempotence/README.md
+    - Mapper:
+      - Overview: mapper/README.md
+      - Entities: mapper/entities/README.md
+      - DAOs: mapper/daos/README.md
+      - Mapper: mapper/mapper/README.md
+      - Configuration: mapper/config/README.md
+    - Developer:
+      - Overview: developer/README.md
+      - Common: developer/common/README.md
+      - Native Protocol: developer/native_protocol/README.md
+      - Netty Pipeline: developer/netty_pipeline/README.md
+      - Request Execution: developer/request_execution/README.md
+      - Admin: developer/admin/README.md
+    - OSGi: osgi/README.md
+  - API References: api/index.html
+  - FAQ: faq-README.md
+  - Changelog: changelog-README.md
+  - Upgrade Guide: upgrade-README.md
+
+plugins:
+  - search
+  - awesome-pages

mkdocs.yml

@@ -804,6 +804,23 @@ limitations under the License.]]></inlineHeader>
           <quiet>true</quiet>
           <doclint>all,-missing</doclint>
           <excludePackageNames>com.datastax.*.driver.internal*</excludePackageNames>
+          <additionalDependencies>
+            <additionalDependency>
+              <groupId>com.google.errorprone</groupId>
+              <artifactId>error_prone_annotations</artifactId>
+              <version>2.3.4</version>
+            </additionalDependency>
+            <additionalDependency>
+              <groupId>com.github.stephenc.jcip</groupId>
+              <artifactId>jcip-annotations</artifactId>
+              <version>1.0-1</version>
+            </additionalDependency>
+            <additionalDependency>
+              <groupId>com.github.spotbugs</groupId>
+              <artifactId>spotbugs-annotations</artifactId>
+              <version>3.1.12</version>
+            </additionalDependency>
+          </additionalDependencies>
           <tags>
             <tag>
               <name>apiNote</name>
@@ -882,7 +899,49 @@ limitations under the License.]]></inlineHeader>
               <useStandardDocletOptions>false</useStandardDocletOptions>
             </configuration>
           </execution>
+          <execution>
+            <!-- Generate aggregated Javadoc for specified modules -->
+            <id>aggregate-javadoc</id>
+            <goals>
+              <goal>aggregate</goal>
+            </goals>
+            <phase>site</phase>
+            <configuration>
+              <includeDependencySources>false</includeDependencySources>
+              <dependencySourceIncludes>
+                <dependencySourceInclude>org.apache.cassandra:java-driver-core</dependencySourceInclude>
+                <dependencySourceInclude>org.apache.cassandra:java-driver-query-builder</dependencySourceInclude>
+                <dependencySourceInclude>org.apache.cassandra:java-driver-mapper-runtime</dependencySourceInclude>
+              </dependencySourceIncludes>
+              <reactorProjects>
+                <reactorProject>core</reactorProject>
+                <reactorProject>query-builder</reactorProject>
+                <reactorProject>mapper-runtime</reactorProject>
+              </reactorProjects>
+              <doctitle>Apache Cassandra Java Driver ${project.version} API</doctitle>
+              <bottom><![CDATA[
+                Copyright &#169; {inceptionYear}&#x2013;{currentYear} <a href="https://www.apache.org/">The Apache Software Foundation</a>. All rights reserved.
+                ]]></bottom>
+            </configuration>
+          </execution>
         </executions>
+        <dependencies>
+          <dependency>
+            <groupId>com.google.errorprone</groupId>
+            <artifactId>error_prone_annotations</artifactId>
+            <version>2.3.4</version>
+          </dependency>
+          <dependency>
+            <groupId>com.github.stephenc.jcip</groupId>
+            <artifactId>jcip-annotations</artifactId>
+            <version>1.0-1</version>
+          </dependency>
+          <dependency>
+            <groupId>com.github.spotbugs</groupId>
+            <artifactId>spotbugs-annotations</artifactId>
+            <version>3.1.12</version>
+          </dependency>
+        </dependencies>
       </plugin>
       <plugin>
         <artifactId>maven-release-plugin</artifactId>