docs: single toctree

README-dev.rst

@@ -20,16 +20,54 @@ Run the following command to build the docs.
 
 Once the command completes processing, open http://127.0.0.1:5500/ with your preferred browser.
 
+To know more about how docs are generated, see `Sphinx ScyllaDB Theme <https://sphinx-theme.scylladb.com/>`_. 
+
 Building multiple documentation versions
 ========================================
 
-Build Sphinx docs for all the versions defined in ``docs/conf.py``.
+Build Sphinx docs for all the versions defined in `docs/conf.py <https://sphinx-theme.scylladb.com/stable/configuration.html#defining-supported-versions>`_.
 
 .. code:: console
 
     cd docs
-    make multiversion
+    make multiversionpreview
 
-Then, open ``docs/_build/dirhtml/<version>/index.html`` with your preferred browser.
+Once the command completes processing, open http://0.0.0.0:5500/ with your preferred browser.
 
 **NOTE:** If you only can see docs generated for the master branch, try to run ``git fetch --tags`` to download the latest tags from remote.
+
+Defining supported versions
+===========================
+
+This repository mirrors DataStax's `java-driver <https://github.com/datastax/java-driver>`_ with custom features and bug fixes to be compatible with ScyllaDB.
+
+Every time there is a new upstream version, the DataStax repository changes are taken as the base, and the previous custom commits are cherry-picked on top.
+This workflow differs from how other forked driver repositories are maintained, where all changes from upstream are integrated into a default branch (typically master or latest).
+
+In practice, we need to port the documentation generator and custom changes done for every new release, as we do with code changes that are not available in the latest upstream version.
+
+**Steps**
+
+Let's say you want to generate docs for the version ``1.0-scylla``.
+You have already ported the custom ScyllaDB changes to the target branch, but you want to publish HTML docs for the new version.
+
+1. Copy the next files from ``latest`` to the branch you want to enable docs generation. For our case, this would be a branch named ``1.0-scylla``.
+
+    * ``docs``: Contains the documentation generation system and how docs are structured.
+    * ``README.md``: A custom page describing the specifics for the ScyllaDB plugin.
+
+2. Commit & push the copied files into the target branch. Make sure the docs build without errors:
+
+    .. code:: console
+
+        cd docs
+        make preview
+
+3. Move back to the ``latest`` branch. List the target version in ``docs/conf.py``.
+
+    .. code:: python
+
+        BRANCHES = ['1.0-scylla']
+        smv_branch_whitelist = multiversion_regex_builder(BRANCHES)
+
+4. Commit & push the changes to the ``latest`` branch.

docs/_utils/javadoc.sh

@@ -12,5 +12,6 @@ fi
 
 # Generate javadoc
 mvn javadoc:javadoc
+[ -d $OUTPUT_DIR ] && rm -r $OUTPUT_DIR
 mkdir -p "$OUTPUT_DIR"
 mv -f driver-core/target/site/apidocs/* $OUTPUT_DIR

docs/source/conf.py

@@ -179,6 +179,8 @@ class DitaaLexer(BashLexer):
 # Dictionary of values to pass into the template engine’s context for all pages
 html_context = {'html_baseurl': html_baseurl}
 
+# Supress warnings
+suppress_warnings = ['autosectionlabel.*']
 # -- Options for not found extension -------------------------------------------
 
 # Template used to render the 404.html generated by this extension.

docs/source/contents.rst

@@ -1,10 +1,35 @@
 .. toctree::
+   :maxdepth: 2
    :hidden:
    :glob:
+   :caption: Getting Started
 
    index
    api
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :glob:
+   :caption: Manual
+
    manual/*
+   manual/**
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :glob:
+   :caption: Upgrade Guide
+
    upgrade_guide/*
+   upgrade_guide/**
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :glob:
+   :caption: FAQ
+
    faq/*
-   changelog/*
+   faq/**

faq/osgi/README.md

@@ -1,6 +1,3 @@
-```eval_rst
-:orphan:
-```
 ## Frequently Asked Questions - OSGi
 
 ### How to use the Java driver in an OSGi environment?

manual/README.md

@@ -305,38 +305,3 @@ simply navigate to each sub-directory.
 [SchemaChangeListener]: https://docs.datastax.com/en/drivers/java/3.10/com/datastax/driver/core/SchemaChangeListener.html
 [NoHostAvailableException]: https://docs.datastax.com/en/drivers/java/3.10/com/datastax/driver/core/exceptions/NoHostAvailableException.html
 [LocalDate]: https://docs.datastax.com/en/drivers/java/3.10/com/datastax/driver/core/LocalDate.html
-
-```eval_rst
-.. toctree::
-   :hidden:
-   :glob:
-
-   address_resolution/*
-   async/*
-   auth/*
-   cloud/*
-   compression/*
-   control_connection/*
-   custom_codecs/*
-   custom_payloads/*
-   idempotence/*
-   load_balancing/*
-   logging/*
-   metadata/*
-   metrics/*
-   native_protocol/*
-   object_mapper/*
-   osgi/*
-   paging/*
-   pooling/*
-   query_timestamps/*
-   reconnection/*
-   retries/*
-   shaded_jar/*
-   socket_options/*
-   speculative_execution/*
-   ssl/*
-   statements/*
-   tuples/*
-   udts/*
-```

manual/custom_codecs/extras/README.md

@@ -1,6 +1,3 @@
-```eval_rst
-:orphan:
-```
 ## Optional codecs
 
 The driver's "extras" module provides additional [codec](../) implementations: these codecs are not required by core

manual/object_mapper/README.md

@@ -21,12 +21,3 @@ See the child pages for more information:
 * [using the mapper](using/)
 * [using custom codecs](custom_codecs/)
 
-```eval_rst
-.. toctree::
-   :hidden:
-   :glob:
-
-   creating/*
-   custom_codecs/*
-   using/*
-```

manual/statements/README.md

@@ -40,14 +40,3 @@ wrap your statements in a custom [StatementWrapper] implementation.
 [SpeculativeExecutionPolicy]: https://docs.datastax.com/en/drivers/java/3.10/com/datastax/driver/core/policies/SpeculativeExecutionPolicy.html
 [execute]:                    https://docs.datastax.com/en/drivers/java/3.10/com/datastax/driver/core/Session.html#execute-com.datastax.driver.core.Statement-
 [executeAsync]:               https://docs.datastax.com/en/drivers/java/3.10/com/datastax/driver/core/Session.html#executeAsync-com.datastax.driver.core.Statement-
-
-```eval_rst
-.. toctree::
-   :hidden:
-   :glob:
-
-   simple/*
-   prepared/*
-   built/*
-   batch/*
-```

upgrade_guide/README.md

@@ -827,10 +827,3 @@ exhaustive list of new features in 2.0.
       (`ResultSet#getAvailableWithoutFetching` and `ResultSet#isFullyFetched`)
       as well as a mean to force the pre-fetching of the next page (`ResultSet#fetchMoreResults`).
 
-```eval_rst
-.. toctree::
-   :hidden:
-   :glob:
-
-   migrating_from_astyanax/*
-```

upgrade_guide/migrating_from_astyanax/README.md

@@ -9,12 +9,3 @@ See the child pages for more information:
 * [Migrating Astyanax configurations to DataStax Java driver configurations](configuration/)
 * [Querying and retrieving results comparisons.](queries_and_results/)
 
-```eval_rst
-.. toctree::
-   :hidden:
-   :glob:
-
-   configuration/*
-   language_level_changes/*
-   queries_and_results/*
-```