fix broken links. substitute links at doc outside /manual

Author: SiyaoIsHiding

.python-version

@@ -0,0 +1 @@
+3.10.1

README.md

@@ -45,8 +45,8 @@ are multiple modules, all prefixed with `java-driver-`.
 Note that the query builder is now published as a separate artifact, you'll need to add the
 dependency if you plan to use it.
 
-Refer to each module's manual for more details ([core](manual/core/), [query
-builder](manual/query_builder/), [mapper](manual/mapper)).
+Refer to each module's manual for more details ([core](/manual/core/README.md), [query
+builder](/manual/query_builder/README.md), [mapper](/manual/mapper/README.md)).
 
 [org.apache.cassandra]: http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.apache.cassandra%22
 
@@ -65,15 +65,15 @@ but DataStax does not officially support these systems.
 Java Driver 4 is **not binary compatible** with previous versions. However, most of the concepts
 remain unchanged, and the new API will look very familiar to 2.x and 3.x users.
 
-See the [upgrade guide](upgrade_guide/) for details.
+See the [upgrade guide](upgrade_guide/README.md) for details.
 
 ## Error Handling
 
 See the [Cassandra error handling done right blog](https://www.datastax.com/blog/cassandra-error-handling-done-right) for error handling with the Java Driver for Apache Cassandra™.
 
 ## Useful links
 
-* [Manual](manual/)
+* [Manual](/manual/README.md)
 * [API docs]
 * Bug tracking: [JIRA]
 * [Mailing list]
@@ -83,8 +83,8 @@ See the [Cassandra error handling done right blog](https://www.datastax.com/blog
 [API docs]: https://docs.datastax.com/en/drivers/java/4.17
 [JIRA]: https://issues.apache.org/jira/issues/?jql=project%20%3D%20CASSJAVA%20ORDER%20BY%20key%20DESC
 [Mailing list]: https://groups.google.com/a/lists.datastax.com/forum/#!forum/java-driver-user
-[Changelog]: changelog/
-[FAQ]: faq/
+[Changelog]: changelog/README.md
+[FAQ]: faq/README.md
 
 ## License
 

build-doc.sh

@@ -1,7 +1,7 @@
 set -e
 # Set up python environment
 #pyenv local 3.10.1
-#pip install mkdocs mkdocs-material pip install mkdocs-awesome-pages-plugin
+#pip install mkdocs mkdocs-material mkdocs-awesome-pages-plugin mkdocs-macros-plugin
 
 # In some bash/zsh environments, the locale is not set correctly, which causes mkdocs to fail.
 export LC_ALL=en_US.UTF-8
@@ -12,5 +12,19 @@ mvn clean install -DskipTests # or guava-shaded can not be found
 # mvn javadoc:javadoc -pl core,query-builder,mapper-runtime
 mvn javadoc:aggregate
 
+
+for f in HOME-README.md faq-README.md upgrade-README.md; do
+  perl -pi -e 's/\]\(\.\.\/manual\//](manual\//g;
+               s/\]\(\.\.\/faq\//](faq\//g;
+               s/\]\(\.\.\/changelog\//](changelog\//g;' "$f"
+done
+
+
 # Build manual with API references
 mkdocs build # or `mkdocs serve` to preview
+
+for f in HOME-README.md faq-README.md upgrade-README.md; do
+  perl -pi -e 's/\]\(manual\//]\(..\/manual\//g;
+               s/\]\(faq\//]\(..\/faq\//g;
+               s/\]\(changelog\//]\(..\/changelog\//g;' "$f"
+done

docs.yaml

@@ -0,0 +1,60 @@
+# 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.
+
+title:    Java Driver
+summary:  Java Driver for Apache Cassandra®
+homepage: http://docs.datastax.com/en/developer/java-driver
+theme: datastax
+sections:
+  - title:     Manual
+    prefix:    /manual
+    sources:
+      - type:  markdown
+        files: 'manual/**/*.md'
+  - title:     Reference configuration
+    prefix:    /manual/core/configuration/reference
+    sources:
+      - type: rst
+        files: 'manual/core/configuration/reference/*.rst'
+  - title:     Changelog
+    prefix:    /changelog
+    sources:
+      - type:  markdown
+        files: 'changelog/**/*.md'
+  - title:     Upgrading
+    prefix:    /upgrade_guide
+    sources:
+      - type:  markdown
+        files: 'upgrade_guide/**/*.md'
+  - title:     FAQ
+    prefix:    /faq
+    sources:
+      - type:  markdown
+        files: 'faq/**/*.md'
+links:
+  - title: Code
+    href:  https://github.com/datastax/java-driver/
+  - title: Docs
+    href:  http://docs.datastax.com/en/developer/java-driver
+  - title: Issues
+    href:  https://datastax-oss.atlassian.net/browse/JAVA/
+  - title: Mailing List
+    href:  https://groups.google.com/a/lists.datastax.com/forum/#!forum/java-driver-user
+  - title: Releases
+    href:  https://github.com/datastax/java-driver/releases
+api_docs:
+  4.0: http://docs.datastax.com/en/drivers/java/4.0

faq/README.md

@@ -65,7 +65,7 @@ At any rate, `CompletionStage` has a `toCompletableFuture()` method. In current
 ### Where is `DowngradingConsistencyRetryPolicy` from driver 3?
 
 **As of driver 4.10, this retry policy was made available again as a built-in alternative to the 
-default retry policy**: see the [manual](../manual/core/retries) to understand how to use it. 
+default retry policy**: see the [manual](manual/core/retries/README.md) to understand how to use it. 
 For versions between 4.0 and 4.9 inclusive, there is no built-in equivalent of driver 3 
 `DowngradingConsistencyRetryPolicy`.
 
@@ -100,7 +100,7 @@ This ability is considered a misfeature and has been removed from driver 4.0 onw
 However, due to popular demand, cross-datacenter failover has been brought back to driver 4 in
 version 4.10.0.
 
-If you are using a driver version >= 4.10.0, read the [manual](../manual/core/loadbalancing/) to
+If you are using a driver version >= 4.10.0, read the [manual](manual/core/loadbalancing/README.md) to
 understand how to enable this feature; for driver versions < 4.10.0, this feature is simply not
 available.
 
@@ -109,7 +109,7 @@ available.
 The driver now uses Java 8's improved date and time API. CQL type `timestamp` is mapped to
 `java.time.Instant`, and the corresponding getter and setter are `getInstant` and `setInstant`.
 
-See [Temporal types](../manual/core/temporal_types/) for more details.
+See [Temporal types](manual/core/temporal_types/README.md) for more details.
 
 ### Why do DDL queries have a higher latency than driver 3?
 
@@ -119,6 +119,6 @@ noticeably higher latency than driver 3 (about 1 second).
 This is because those queries are now *debounced*: the driver adds a short wait in an attempt to
 group multiple schema changes into a single metadata refresh. If you want to mitigate this, you can
 either adjust the debouncing settings, or group your schema updates while temporarily disabling the
-metadata; see the [performance](../manual/core/performance/#debouncing) page.
+metadata; see the [performance](manual/core/performance/#debouncing/README.md) page.
 
 This only applies to DDL queries; DML statements (`SELECT`, `INSERT`...) are not debounced.

manual/HOME-README.md

@@ -0,0 +1,111 @@
+# Java Driver for Apache Cassandra®
+
+:warning: The java-driver has recently been donated by Datastax to The Apache Software Foundation and the Apache Cassandra project.  Bear with us as we move assets and coordinates.
+
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Maven Central](https://maven-badges.herokuapp.com/maven-central/org.apache.cassandra/java-driver-core/badge.svg)](https://maven-badges.herokuapp.com/maven-central/org.apache.cassandra/java-driver-core)
+
+*If you're reading this on github.com, please note that this is the readme for the development 
+version and that some features described here might not yet have been released. You can find the
+documentation for latest version through [DataStax Docs] or via the release tags, e.g. 
+[4.17.0](https://github.com/datastax/java-driver/tree/4.17.0).*
+
+A modern, feature-rich and highly tunable Java client library for [Apache Cassandra®] \(2.1+) and 
+[DataStax Enterprise] \(4.7+), and [DataStax Astra], using exclusively Cassandra's binary protocol
+and Cassandra Query Language (CQL) v3.
+
+[DataStax Docs]: http://docs.datastax.com/en/developer/java-driver/
+[Apache Cassandra®]: http://cassandra.apache.org/
+
+## Getting the driver
+
+The driver artifacts are published in Maven central, under the group id [com.datastax.oss]; there
+are multiple modules, all prefixed with `java-driver-`.
+
+```xml
+<dependency>
+  <groupId>org.apache.cassandra</groupId>
+  <artifactId>java-driver-core</artifactId>
+  <version>${driver.version}</version>
+</dependency>
+
+<dependency>
+  <groupId>org.apache.cassandra</groupId>
+  <artifactId>java-driver-query-builder</artifactId>
+  <version>${driver.version}</version>
+</dependency>
+
+<dependency>
+  <groupId>org.apache.cassandra</groupId>
+  <artifactId>java-driver-mapper-runtime</artifactId>
+  <version>${driver.version}</version>
+</dependency>
+```
+
+Note that the query builder is now published as a separate artifact, you'll need to add the
+dependency if you plan to use it.
+
+Refer to each module's manual for more details ([core](/manual/core/README.md), [query
+builder](/manual/query_builder/README.md), [mapper](/manual/mapper/README.md)).
+
+[com.datastax.oss]: http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22com.datastax.oss%22
+
+## Compatibility
+
+The driver is compatible with Apache Cassandra® 2.1 and higher, DataStax Enterprise 4.7 and
+higher, and DataStax Astra.
+
+It requires Java 8 or higher.
+
+Disclaimer: Some DataStax/DataStax Enterprise products might partially work on big-endian systems,
+but DataStax does not officially support these systems.
+
+## Migrating from previous versions
+
+Java Driver 4 is **not binary compatible** with previous versions. However, most of the concepts
+remain unchanged, and the new API will look very familiar to 2.x and 3.x users.
+
+See the [upgrade guide](upgrade_guide/README.md) for details.
+
+## Error Handling
+
+See the [Cassandra error handling done right blog](https://www.datastax.com/blog/cassandra-error-handling-done-right) for error handling with the Java Driver for Apache Cassandra&trade;.
+
+## Useful links
+
+* [Manual](/manual/README.md)
+* [API docs]
+* Bug tracking: [JIRA]
+* [Mailing list]
+* [Changelog]
+* [FAQ]
+
+[API docs]: https://docs.datastax.com/en/drivers/java/4.17
+[JIRA]: https://issues.apache.org/jira/issues/?jql=project%20%3D%20CASSJAVA%20ORDER%20BY%20key%20DESC
+[Mailing list]: https://groups.google.com/a/lists.datastax.com/forum/#!forum/java-driver-user
+[Changelog]: changelog/README.md
+[FAQ]: faq/README.md
+
+## License
+
+&copy; The Apache Software Foundation
+
+Licensed 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.
+
+----
+
+Apache Cassandra, Apache, Tomcat, Lucene, Solr, Hadoop, Spark, TinkerPop, and Cassandra are 
+trademarks of the [Apache Software Foundation](http://www.apache.org/) or its subsidiaries in
+Canada, the United States and/or other countries. 
+
+Binary artifacts of this product bundle Java Native Runtime libraries, which is available under the Eclipse Public License version 2.0.

manual/HOME-README.md

@@ -21,16 +21,16 @@ under the License.
 
 Driver modules:
 
-* [Core](core/): the main entry point, deals with connectivity and query execution.
-* [Query builder](query_builder/): a fluent API to create CQL queries programmatically.
-* [Mapper](mapper/): generates the boilerplate to execute queries and convert the results into
+* [Core](core/README.md): the main entry point, deals with connectivity and query execution.
+* [Query builder](query_builder/README.md): a fluent API to create CQL queries programmatically.
+* [Mapper](mapper/README.md): generates the boilerplate to execute queries and convert the results into
   application-level objects.
-* [Developer docs](developer/): explains the codebase and internal extension points for advanced
+* [Developer docs](developer/README.md): explains the codebase and internal extension points for advanced
   customization.
 
 Common topics:
 
-* [API conventions](api_conventions/)
-* [Case sensitivity](case_sensitivity/)
-* [OSGi](osgi/)
-* [Cloud](cloud/)
+* [API conventions](api_conventions/README.md)
+* [Case sensitivity](case_sensitivity/README.md)
+* [OSGi](osgi/README.md)
+* [Cloud](cloud/README.md)

manual/README.md

@@ -146,5 +146,5 @@ public class Main {
 [Create an Astra database - AWS/Azure/GCP]: https://docs.datastax.com/en/astra/docs/creating-your-astra-database.html
 [Access an Astra database - AWS/Azure/GCP]: https://docs.datastax.com/en/astra/docs/obtaining-database-credentials.html#_sharing_your_secure_connect_bundle
 [Download the secure connect bundle - AWS/Azure/GCP]: https://docs.datastax.com/en/astra/docs/obtaining-database-credentials.html
-[minimal project structure]: ../core/integration/#minimal-project-structure
-[driver documentation]: ../core/configuration/
+[minimal project structure]: ../core/integration/README.md#minimal-project-structure
+[driver documentation]: ../core/configuration/README.md