diff --git a/README-dev.rst b/README-dev.rst index ee4b7f30ed7..166c2d04147 100644 --- a/README-dev.rst +++ b/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 `_. + 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 `_. .. code:: console cd docs - make multiversion + make multiversionpreview -Then, open ``docs/_build/dirhtml//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 `_ 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. \ No newline at end of file diff --git a/docs/_utils/javadoc.sh b/docs/_utils/javadoc.sh index 448375eccce..5ec6ab16dc0 100755 --- a/docs/_utils/javadoc.sh +++ b/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 diff --git a/docs/source/changelog b/docs/source/changelog deleted file mode 120000 index 2281eaa6b7b..00000000000 --- a/docs/source/changelog +++ /dev/null @@ -1 +0,0 @@ -../../changelog/ \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index b936c86ca83..761279e12bf 100644 --- a/docs/source/conf.py +++ b/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. diff --git a/docs/source/contents.rst b/docs/source/contents.rst index c18c6fa3eba..e03925329a4 100644 --- a/docs/source/contents.rst +++ b/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/* \ No newline at end of file + faq/** diff --git a/faq/osgi/README.md b/faq/osgi/README.md index 06f780333fe..dd01626e2db 100644 --- a/faq/osgi/README.md +++ b/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? diff --git a/manual/README.md b/manual/README.md index 49cda94a082..f7c0dc2b816 100644 --- a/manual/README.md +++ b/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/* -``` \ No newline at end of file diff --git a/manual/custom_codecs/extras/README.md b/manual/custom_codecs/extras/README.md index 7e71f7dbe5a..a8190d3235f 100644 --- a/manual/custom_codecs/extras/README.md +++ b/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 diff --git a/manual/object_mapper/README.md b/manual/object_mapper/README.md index ffc8fb4b764..00c97ee230c 100644 --- a/manual/object_mapper/README.md +++ b/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/* -``` diff --git a/manual/statements/README.md b/manual/statements/README.md index 9a941c30128..865818796d0 100644 --- a/manual/statements/README.md +++ b/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/* -``` diff --git a/upgrade_guide/README.md b/upgrade_guide/README.md index 081cb571c26..d3dacb1d3a6 100644 --- a/upgrade_guide/README.md +++ b/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/* -``` \ No newline at end of file diff --git a/upgrade_guide/migrating_from_astyanax/README.md b/upgrade_guide/migrating_from_astyanax/README.md index c899252d63d..9e4fd47729c 100644 --- a/upgrade_guide/migrating_from_astyanax/README.md +++ b/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/* -``` \ No newline at end of file