Documentation: Add/reactivate documentation as sqlalchemy-cratedb

Author: amotl

.gitignore

@@ -6,4 +6,5 @@
 *.pyc
 .coverage
 coverage.xml
-dist/
+/build
+/dist

CHANGES.md

@@ -2,6 +2,7 @@
 
 
 ## Unreleased
+- Added/reactivated documentation as `sqlalchemy-cratedb`
 
 ## 2024/06/13 0.37.0
 - Added support for CrateDB's [FLOAT_VECTOR] data type and its accompanying

README.md

@@ -26,11 +26,12 @@ pip install --upgrade sqlalchemy-cratedb
 
 ## Documentation and help
 
-- [CrateDB Python Client documentation](https://crate.io/docs/python/)
-- [CrateDB reference documentation](https://crate.io/docs/reference/)
+- [SQLAlchemy dialect for CrateDB](https://cratedb.com/docs/sqlalchemy-cratedb/)
+- [CrateDB Python Client documentation](https://cratedb.com/docs/python/)
+- [CrateDB reference documentation](https://cratedb.com/docs/reference/)
 - [Developer documentation](DEVELOP.md)
 - [Contributing](CONTRIBUTING.md)
-- Other [support channels](https://crate.io/support/)
+- Other [support channels](https://cratedb.com/support)
 
 ## Contributing
 

bootstrap.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 #
-# Bootstrap sandbox environment for crate-python
+# Bootstrap sandbox environment for sqlalchemy-cratedb
 #
 # - Create a Python virtualenv
 # - Install all dependency packages and modules

docs/advanced-querying.rst

@@ -205,7 +205,7 @@ Using the ``group_by`` clause is similar:
 
 In SQLAlchemy, the ``insert().from_select()`` function returns a new ``Insert``
 construct, which represents an ``INSERT...FROM SELECT`` statement. This
-functionality is supported by the CrateDB client library. Here is an example
+functionality is supported by the SQLAlchemy CrateDB dialect. Here is an example
 that uses ``insert().from_select()``.
 
 First, let's define and create the tables:

docs/build.json

@@ -1,5 +1,5 @@
 {
   "schemaVersion": 1,
   "label": "docs build",
-  "message": "2.1.1"
+  "message": "2.1.2"
 }

docs/conf.py

@@ -1,8 +1,4 @@
-from crate.theme.rtd.conf.python import *
-
-
-if "sphinx.ext.intersphinx" not in extensions:
-    extensions += ["sphinx.ext.intersphinx"]
+from crate.theme.rtd.conf.sqlalchemy_cratedb import *
 
 
 if "intersphinx_mapping" not in globals():
@@ -12,7 +8,6 @@
 intersphinx_mapping.update({
     'py': ('https://docs.python.org/3/', None),
     'sa': ('https://docs.sqlalchemy.org/en/20/', None),
-    'urllib3': ('https://urllib3.readthedocs.io/en/1.26.13/', None),
     'dask': ('https://docs.dask.org/en/stable/', None),
     'pandas': ('https://pandas.pydata.org/docs/', None),
     })

docs/index-all.rst

@@ -0,0 +1,20 @@
+:orphan:
+
+.. _index-all:
+
+#######################################
+CrateDB SQLAlchemy dialect -- all pages
+#######################################
+
+
+.. rubric:: Table of contents
+
+.. toctree::
+    :maxdepth: 2
+
+    getting-started
+    crud
+    working-with-types
+    advanced-querying
+    inspection-reflection
+    dataframe

docs/index.rst

@@ -11,12 +11,13 @@ SQLAlchemy dialect for CrateDB
     :depth: 1
 
 
-************
-Introduction
-************
+*****
+About
+*****
 
 The :ref:`CrateDB dialect <using-sqlalchemy>` for `SQLAlchemy`_ provides adapters
 for `CrateDB`_ and SQLAlchemy. The supported versions are 1.3, 1.4, and 2.0.
+The package is available from `PyPI`_ at `sqlalchemy-cratedb`_.
 
 The connector can be used to connect to both `CrateDB`_ and `CrateDB
 Cloud`_, and is verified to work on Linux, macOS, and Windows. It is used by
@@ -25,29 +26,40 @@ CrateDB from the Python ecosystem. It is verified to work with CPython, but
 it has also been tested successfully with `PyPy`_.
 
 
-*************
-Documentation
-*************
+************
+Introduction
+************
 
 Please consult the `SQLAlchemy tutorial`_, and the general `SQLAlchemy
 documentation`_.
-For more detailed information about how to install the client driver, how to
+For more detailed information about how to install the dialect package, how to
 connect to a CrateDB cluster, and how to run queries, consult the resources
 referenced below.
 
+
+************
+Installation
+************
+
+Install package from PyPI.
+
+.. code-block:: shell
+
+    pip install --upgrade sqlalchemy-cratedb
+
+More installation details can be found over here.
+
 .. toctree::
     :titlesonly:
 
     install
 
-SQLAlchemy
-==========
 
-Install package from PyPI.
+.. _features:
 
-.. code-block:: shell
-
-    pip install sqlalchemy-cratedb
+********
+Features
+********
 
 The CrateDB dialect for `SQLAlchemy`_ offers convenient ORM access and supports
 CrateDB's container data types ``OBJECT`` and ``ARRAY``, its vector data type
@@ -59,23 +71,20 @@ kinds of `GeoJSON geometry objects`_.
 
     overview
 
-Install package from PyPI with DB API and SQLAlchemy support.
 
-.. code-block:: shell
+.. _synopsis:
 
-    pip install sqlalchemy-cratedb pandas
+Synopsis
+========
 
 Connect to CrateDB instance running on ``localhost``.
 
 .. code-block:: python
 
     # Connect using SQLAlchemy Core.
-    import pkg_resources
     import sqlalchemy as sa
     from pprint import pp
 
-    pkg_resources.require("sqlalchemy>=2.0")
-    
     dburi = "crate://localhost:4200"
     query = "SELECT country, mountain, coordinates, height FROM sys.summits ORDER BY country;"
     
@@ -95,6 +104,10 @@ Connect to `CrateDB Cloud`_.
 
 Load results into `pandas`_ DataFrame.
 
+.. code-block:: shell
+
+    pip install pandas
+
 .. code-block:: python
 
     # Connect using SQLAlchemy Core and pandas.
@@ -114,13 +127,15 @@ Load results into `pandas`_ DataFrame.
 Data types
 ==========
 
-The DB API driver and the SQLAlchemy dialect support :ref:`CrateDB's data types
-<crate-reference:data-types>` to different degrees. For more information,
-please consult the :ref:`data-types` and :ref:`SQLAlchemy extension types
-<using-extension-types>` documentation pages.
+The :ref:`DB API driver <crate-python:index>` and the SQLAlchemy dialect
+support :ref:`CrateDB's data types <crate-reference:data-types>` to different
+degrees.
+For more information, please consult the :ref:`data-types` and :ref:`SQLAlchemy
+extension types <using-extension-types>` documentation pages.
 
 .. toctree::
     :maxdepth: 2
+    :hidden:
 
     data-types
 
@@ -129,8 +144,9 @@ please consult the :ref:`data-types` and :ref:`SQLAlchemy extension types
 .. _by-example:
 .. _sqlalchemy-by-example:
 
+********
 Examples
-========
+********
 
 This section enumerates concise examples demonstrating the
 use of the SQLAlchemy dialect.
@@ -145,15 +161,12 @@ use of the SQLAlchemy dialect.
     inspection-reflection
     dataframe
 
+.. rubric:: See also
 
-See also
---------
 - Executable code examples are maintained within the `cratedb-examples repository`_.
-- The `sample application`_ and the corresponding `sample application
-  documentation`_ demonstrate the use of the driver on behalf of an example
-  "guestbook" application.
-- `Use CrateDB with pandas`_ has corresponding code snippets about how to
-  connect to CrateDB using `pandas`_, and how to load and export data.
+- `Using CrateDB with pandas, Dask, and Polars`_ has corresponding code snippets
+  about how to connect to CrateDB using popular data frame libraries, and how to
+  load and export data.
 - The `Apache Superset`_ and `FIWARE QuantumLeap data historian`_ projects.
 
 
@@ -164,13 +177,13 @@ Project information
 
 Resources
 =========
-- `Source code <https://github.com/crate/crate-python>`_
-- `Documentation <https://crate.io/docs/python/>`_
-- `Python Package Index (PyPI) <https://pypi.org/project/crate/>`_
+- `Source code <https://github.com/crate-workbench/sqlalchemy-cratedb>`_
+- `Documentation <https://github.com/crate-workbench/sqlalchemy-cratedb>`_
+- `Python Package Index (PyPI) <https://pypi.org/project/sqlalchemy-cratedb/>`_
 
 Contributions
 =============
-The CrateDB Python client library is an open source project, and is `managed on
+The SQLAlchemy dialect for CrateDB is an open source project, and is `managed on
 GitHub`_.
 Every kind of contribution, feedback, or patch, is much welcome. `Create an
 issue`_ or submit a patch if you think we should include a new feature, or to
@@ -193,24 +206,23 @@ The project is licensed under the terms of the Apache 2.0 license, like
 
 
 .. _Apache Superset: https://github.com/apache/superset
-.. _Crash CLI: https://crate.io/docs/crate/crash/
 .. _CrateDB: https://crate.io/products/cratedb
 .. _CrateDB Cloud: https://console.cratedb.cloud/
 .. _CrateDB source: https://github.com/crate/crate
-.. _Create an issue: https://github.com/crate/crate-python/issues
-.. _development sandbox: https://github.com/crate/crate-python/blob/master/DEVELOP.rst
+.. _Create an issue: https://github.com/crate-workbench/sqlalchemy-cratedb/issues
+.. _development sandbox: https://github.com/crate-workbench/sqlalchemy-cratedb/blob/main/DEVELOP.md
 .. _cratedb-examples repository: https://github.com/crate/cratedb-examples/tree/main/by-language
 .. _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
+.. _LICENSE: https://github.com/crate-workbench/sqlalchemy-cratedb/blob/main/LICENSE
+.. _managed on GitHub: https://github.com/crate-workbench/sqlalchemy-cratedb
 .. _pandas: https://pandas.pydata.org/
 .. _PEP 249: https://peps.python.org/pep-0249/
+.. _PyPI: https://pypi.org/
 .. _PyPy: https://www.pypy.org/
-.. _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://www.sqlalchemy.org/
 .. _SQLAlchemy documentation: https://docs.sqlalchemy.org/
 .. _SQLAlchemy tutorial: https://docs.sqlalchemy.org/en/latest/tutorial/
-.. _Use CrateDB with pandas: https://github.com/crate/crate-qa/pull/246
+.. _sqlalchemy-cratedb: https://pypi.org/project/sqlalchemy-cratedb/
+.. _Using CrateDB with pandas, Dask, and Polars: https://github.com/crate/cratedb-examples/tree/main/by-dataframe

docs/install.rst

@@ -4,8 +4,8 @@
 Install
 =======
 
-Learn how to install and get started with the Python client library for
-`CrateDB`_.
+Learn how to install and get started with the SQLAlchemy dialect for
+`CrateDB`_. The package is available from `PyPI`_ at `sqlalchemy-cratedb`_.
 
 .. rubric:: Table of contents
 
@@ -15,12 +15,10 @@ Learn how to install and get started with the Python client library for
 Install
 =======
 
-.. highlight:: sh
-
-The CrateDB Python client is available as package ``sqlalchemy-cratedb`` on `PyPI`_.
-
 To install the most recent driver version, including the SQLAlchemy dialect
-extension, run::
+extension, run:
+
+.. code-block:: shell
 
     pip install --upgrade sqlalchemy-cratedb
 
@@ -42,11 +40,11 @@ and reproducible, achieving `repeatable installations`_.
 Next steps
 ==========
 
-Learn how to :ref:`connect to CrateDB <connect>`.
+Learn how to :ref:`get started <getting-started>`, or how to :ref:`connect to CrateDB <connect>`.
 
 
-.. _sqlalchemy-cratedb: https://pypi.org/project/sqlalchemy-cratedb/
-.. _CrateDB: https://crate.io/products/cratedb/
+.. _CrateDB: https://cratedb.com/database
 .. _many ways: https://packaging.python.org/key_projects/
 .. _PyPI: https://pypi.org/
 .. _repeatable installations: https://pip.pypa.io/en/latest/topics/repeatable-installs/
+.. _sqlalchemy-cratedb: https://pypi.org/project/sqlalchemy-cratedb/