Documentation: Improve guidance about migrating to sqlalchemy-cratedb

README.rst

@@ -58,7 +58,18 @@ To install the most recent driver version, run::
     $ pip install --upgrade crate
 
 
-Documentation and help
+Migration Notes
+===============
+
+If you are migrating from previous versions of ``crate[sqlalchemy]<1.0.0``, you
+will find that the newer releases ``crate>=1.0.0`` no longer include the
+SQLAlchemy dialect for CrateDB.
+
+See `migrate to sqlalchemy-cratedb`_ for relevant guidelines about how to
+successfully migrate to the `sqlalchemy-cratedb`_ package.
+
+
+Documentation and Help
 ======================
 
 - `CrateDB Python Client documentation`_
@@ -68,8 +79,8 @@ Documentation and help
 - Other `support channels`_
 
 
-Contributing
-============
+Contributions
+=============
 
 The CrateDB Python client library is an open source project, and is `managed on
 GitHub`_. We appreciate contributions of any kind.
@@ -84,6 +95,7 @@ GitHub`_. We appreciate contributions of any kind.
 .. _DB API 2.0: https://peps.python.org/pep-0249/
 .. _Developer documentation: DEVELOP.rst
 .. _managed on GitHub: https://github.com/crate/crate-python
+.. _migrate to sqlalchemy-cratedb: https://cratedb.com/docs/sqlalchemy-cratedb/migrate-from-crate-client.html
 .. _PyPI: https://pypi.org/
 .. _SQLAlchemy: https://www.sqlalchemy.org/
 .. _sqlalchemy-cratedb: https://github.com/crate/sqlalchemy-cratedb

docs/index.rst

@@ -27,9 +27,6 @@ it has also been tested successfully with `PyPy`_.
 Please make sure to also visit the section about :ref:`other-options`, using
 the :ref:`crate-reference:interface-postgresql` interface of `CrateDB`_.
 
-The :ref:`CrateDB dialect <using-sqlalchemy>` for `SQLAlchemy`_ is provided
-by the ``sqlalchemy-cratedb`` package.
-
 
 *************
 Documentation
@@ -98,21 +95,37 @@ please consult the :ref:`data-types` documentation page.
 
     data-types
 
+
+Migration Notes
+===============
+
+The :ref:`CrateDB dialect <using-sqlalchemy>` for `SQLAlchemy`_ is provided
+by the `sqlalchemy-cratedb`_ package.
+
+If you are migrating from previous versions of ``crate[sqlalchemy]<1.0.0``, you
+will find that the newer releases ``crate>=1.0.0`` no longer include the
+SQLAlchemy dialect for CrateDB.
+
+See `migrate to sqlalchemy-cratedb`_ for relevant guidelines about how to
+successfully migrate to the `sqlalchemy-cratedb`_ package.
+
+
 Examples
 ========
 
 - The :ref:`by-example` section enumerates concise examples demonstrating the
   different API interfaces of the CrateDB Python client library. Those are
   DB API, HTTP, and BLOB interfaces.
+
 - Executable code examples are maintained within the `cratedb-examples repository`_.
+  `sqlalchemy-cratedb`_, `python-dataframe-examples`_, and `python-sqlalchemy-examples`_
+  provide relevant code snippets about how to connect to CrateDB using
+  `SQLAlchemy`_, `pandas`_, or `Dask`_, and how to load and export data.
+
 - The `sample application`_ and the corresponding `sample application
   documentation`_ demonstrate the use of the driver on behalf of an example
-  "guestbook" application.
-- ``sqlalchemy-cratedb`` has relevant code snippets about how to
-  connect to CrateDB using `SQLAlchemy`_, `pandas`_, and `Dask`_.
-- `Use CrateDB with pandas`_ has corresponding code snippets about how to
-  connect to CrateDB using `pandas`_, and how to load and export data.
-- The `Apache Superset`_ and `FIWARE QuantumLeap data historian`_ projects.
+  "guestbook" application, using Flask.
+
 
 .. toctree::
     :maxdepth: 2
@@ -162,16 +175,20 @@ The project is licensed under the terms of the Apache 2.0 license, like
 .. _Create an issue: https://github.com/crate/crate-python/issues
 .. _Dask: https://en.wikipedia.org/wiki/Dask_(software)
 .. _development sandbox: https://github.com/crate/crate-python/blob/master/DEVELOP.rst
-.. _cratedb-examples repository: https://github.com/crate/cratedb-examples/tree/main/by-language
+.. _cratedb-examples repository: https://github.com/crate/cratedb-examples
 .. _FIWARE QuantumLeap data historian: https://github.com/orchestracities/ngsi-timeseries-api
 .. _GeoJSON: https://geojson.org/
 .. _GeoJSON geometry objects: https://tools.ietf.org/html/rfc7946#section-3.1
 .. _LICENSE: https://github.com/crate/crate-python/blob/master/LICENSE
 .. _managed on GitHub: https://github.com/crate/crate-python
+.. _migrate to sqlalchemy-cratedb: https://cratedb.com/docs/sqlalchemy-cratedb/migrate-from-crate-client.html
 .. _pandas: https://en.wikipedia.org/wiki/Pandas_(software)
 .. _PEP 249: https://peps.python.org/pep-0249/
 .. _PyPy: https://www.pypy.org/
+.. _python-dataframe-examples: https://github.com/crate/cratedb-examples/tree/main/by-dataframe
+.. _python-sqlalchemy-examples: https://github.com/crate/cratedb-examples/tree/main/by-language/python-sqlalchemy
 .. _sample application: https://github.com/crate/crate-sample-apps/tree/main/python-flask
 .. _sample application documentation: https://github.com/crate/crate-sample-apps/blob/main/python-flask/documentation.md
 .. _SQLAlchemy: https://en.wikipedia.org/wiki/Sqlalchemy
+.. _sqlalchemy-cratedb: https://github.com/crate/sqlalchemy-cratedb
 .. _Use CrateDB with pandas: https://github.com/crate/crate-qa/pull/246