Documentation: Improve landing page and other sections across the board

DEVELOP.rst

@@ -1,12 +1,14 @@
-===============
-Developer guide
-===============
+==============================
+CrateDB Python developer guide
+==============================
 
 Setup
 =====
 
 To start things off, bootstrap the sandbox environment::
 
+ git clone https://github.com/crate/crate-python
+ cd crate-python
  source bootstrap.sh
 
 This command should automatically install all prerequisites for the development

README.rst

@@ -45,50 +45,49 @@ A Python client library for CrateDB_.
 
 This library:
 
-- Implements the Python `DB API 2.0`_ specification
-- Includes support for SQLAlchemy_ (>= 1.3.0)
-
-Prerequisites
-=============
-
-Recent versions of this library are validated on Python 3 (>= 3.7).
-It may also work on earlier versions of Python.
+- Implements the Python `DB API 2.0`_ specification.
+- Includes support for SQLAlchemy_ in form of an `SQLAlchemy dialect`_.
 
 
 Installation
 ============
 
-The CrateDB Python client is available as a pip_ package.
+The CrateDB Python client is available as package `crate`_ on `PyPI`_.
 
 To install the most recent driver version, including the SQLAlchemy dialect
 extension, run::
 
  $ pip install "crate[sqlalchemy]" --upgrade
 
 
-Contributing
-============
+Documentation and help
+======================
 
-This project is primarily maintained by Crate.io_, but we welcome community
-contributions!
+- `CrateDB Python Client documentation`_
+- `CrateDB reference documentation`_
+- `Developer documentation`_
+- `Contributing`_
+- Other `support channels`_
 
-See the `developer docs`_ and the `contribution docs`_ for more information.
 
-Help
-====
+Contributing
+============
 
-Looking for more help?
+The CrateDB Python client library is an open source project, and is `managed on
+GitHub`_. We appreciate contributions of any kind.
 
-- Read the `project docs`_
-- Check out our `support channels`_
 
-.. _contribution docs: CONTRIBUTING.rst
+.. _Contributing: CONTRIBUTING.rst
+.. _crate: https://pypi.org/project/crate/
 .. _Crate.io: https://crate.io/
 .. _CrateDB: https://github.com/crate/crate
-.. _DB API 2.0: http://www.python.org/dev/peps/pep-0249/
-.. _developer docs: DEVELOP.rst
-.. _pip: https://pypi.python.org/pypi/pip
+.. _CrateDB Python Client documentation: https://crate.io/docs/python/
+.. _CrateDB reference documentation: https://crate.io/docs/reference/
+.. _DB API 2.0: https://peps.python.org/pep-0249/
+.. _Developer documentation: DEVELOP.rst
+.. _managed on GitHub: https://github.com/crate/crate-python
+.. _PyPI: https://pypi.org/
 .. _SQLAlchemy: https://www.sqlalchemy.org
+.. _SQLAlchemy dialect: https://docs.sqlalchemy.org/dialects/
 .. _StackOverflow: https://stackoverflow.com/tags/cratedb
 .. _support channels: https://crate.io/support/
-.. _project docs: https://crate.io/docs/python/

docs/by-example/index.rst

@@ -1,3 +1,5 @@
+.. _by-example:
+
 ##########
 By example
 ##########
@@ -11,10 +13,10 @@ This part of the documentation contains examples how to use the CrateDB Python
 client.
 
 
-DBAPI, HTTP, and BLOB interfaces
-================================
+DB API, HTTP, and BLOB interfaces
+=================================
 
-The examples in this section are all about CrateDB's `Python DBAPI`_ interface,
+The examples in this section are all about CrateDB's `Python DB API`_ interface,
 the plain HTTP API interface, and a convenience interface for working with
 :ref:`blob tables <crate-reference:blob_support>`. It details attributes,
 methods, and behaviors of the ``Connection`` and ``Cursor`` objects.
@@ -48,5 +50,5 @@ its corresponding API interfaces, see also :ref:`sqlalchemy-support`.
  sqlalchemy/inspection-reflection
 
 
-.. _Python DBAPI: https://peps.python.org/pep-0249/
+.. _Python DB API: https://peps.python.org/pep-0249/
 .. _SQLAlchemy: https://www.sqlalchemy.org/

docs/getting-started.rst

@@ -4,28 +4,20 @@
 Getting started
 ===============
 
-Learn how to install and get started the :ref:`CrateDB Python client library
-<index>`.
+Learn how to install and get started with the Python client library for
+`CrateDB`_.
 
 .. rubric:: Table of contents
 
 .. contents::
  :local:
 
-Prerequisites
-=============
-
-Recent versions of this library are validated on Python 3 (>= 3.7).
-It may also work on earlier versions of Python.
-
-`Pip`_ should be installed on your system.
-
 Install
 =======
 
 .. highlight:: sh
 
-The CrateDB Python client is `available`_ as a `PyPI`_ package.
+The CrateDB Python client is available as package `crate`_ on `PyPI`_.
 
 To install the most recent driver version, including the SQLAlchemy dialect
 extension, run::
@@ -43,37 +35,42 @@ Interactive use
 
 Python provides a REPL_, also known as an interactive language shell. It's a
 handy way to experiment with code and try out new libraries. We recommend
-`iPython`_, which you can install, like so::
+`IPython`_, which you can install, like so::
 
- pip install iPython
+ pip install ipython
 
 Once installed, you can start it up, like this::
 
  ipython
 
 From there, try importing the CrateDB Python client library and seeing how far
 you get with the built-in ``help()`` function (that can be called on any
-object), iPython's autocompletion, and many other features.
+object), IPython's autocompletion, and many other features.
 
 .. SEEALSO::
 
- `The iPython Documentation`_
+ `The IPython Documentation`_
 
 Set up as a dependency
 ======================
 
-In order to handle Python project dependencies, there are `many ways`_.
-The official PyPI package should be compatible with all of them.
+There are `many ways`_ to add the ``crate`` package as a dependency to your
+project. All of them work equally well. Please note that you may want to employ
+package version pinning in order to keep the environment of your project stable
+and reproducible, achieving `repeatable installations`_.
+
 
 Next steps
 ==========
 
 Learn how to :ref:`connect to CrateDB <connect>`.
 
-.. _available: https://pypi.python.org/pypi/pip
-.. _iPython: https://ipython.org/
+
+.. _crate: https://pypi.org/project/crate/
+.. _CrateDB: https://crate.io/products/cratedb/
+.. _IPython: https://ipython.org/
 .. _many ways: https://packaging.python.org/key_projects/
-.. _Pip: https://pip.pypa.io/en/stable/installing/
 .. _PyPI: https://pypi.org/
+.. _repeatable installations: https://pip.pypa.io/en/latest/topics/repeatable-installs/
 .. _REPL: https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop
-.. _The iPython Documentation: https://ipython.readthedocs.io/en/stable/
+.. _The IPython Documentation: https://ipython.readthedocs.io/

docs/index-all.rst

@@ -0,0 +1,22 @@
+:orphan:
+
+.. _index-all:
+
+##################################
+CrateDB Python Client -- all pages
+##################################
+
+
+.. rubric:: Table of contents
+
+.. toctree::
+ :maxdepth: 2
+
+ getting-started
+ connect
+ query
+ blobs
+ sqlalchemy
+ data-types
+ by-example/index
+ other-options