NG: Thoroughly modernize content and appearance

.github/workflows/docs.yml

@@ -3,7 +3,11 @@ on:
   pull_request: ~
   push:
     branches:
-      - master
+      - main
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
 
 jobs:
   documentation:
@@ -15,11 +19,11 @@ jobs:
         os: [ubuntu-latest, macos-latest]
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - name: Set up Python
-        uses: actions/setup-python@v1
+        uses: actions/setup-python@v4
         with:
-          python-version: 3.7
+          python-version: 3.11
       - name: Build docs
         run: |
           cd docs && make check

.gitignore

@@ -4,6 +4,7 @@
 .crate-docs
 .DS_Store
 .env
+.idea
 .style
 .utils
 *.lint

.readthedocs.yml

@@ -1,11 +1,22 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+
+# Details
+# - https://docs.readthedocs.io/en/stable/config-file/v2.html
+
+# Required
 version: 2
 
+build:
+  os: "ubuntu-22.04"
+  tools:
+    python: "3.11"
+
 sphinx:
   builder: html
   configuration: docs/conf.py
   fail_on_warning: true
 
 python:
-  version: 3.7
   install:
     - requirements: docs/requirements.txt

BACKLOG.md

@@ -0,0 +1,59 @@
+# Backlog
+
+
+## Iteration +1
+- [ ] Add item about Admin UI
+- [ ] Add item about `psycopg3`
+- [ ] Connect: Add more properties, like `schema`
+
+## Iteration +2
+- [ ] Refer to more artefacts/resources
+  - Prometheus (Server Metrics/Monitoring)
+  - Terraform (Administration)
+- [ ] Add section about testing frameworks
+- [ ] Add section "highlights", or "awesome", bundling corresponding resources.
+  - https://community.crate.io/t/how-we-scaled-ingestion-to-one-million-rows-per-second/1069
+- [ ] Add [HTTPie Desktop]
+  Screenshot: https://github.com/crate/crate-clients-tools/assets/453543/9f724518-ee83-43ac-9ea1-7be63e7c9805
+
+## Iteration +3
+- [ ] Drivers: Outline multiple dimensions
+  - protocol: http vs. pg
+  - maintained/unmaintained
+  - recommended
+- [ ] Drivers: Layout overview list/table differently, to better convey more detailed
+  information per item. Maybe use [Info Card].
+
+## Evaluate
+
+- Via https://getsqlpad.com/en/introduction/#alternatives
+  - [Querybook](https://www.querybook.org/) (open source)
+  - [Superset](https://github.com/apache/superset) (open source) / [Preset](https://preset.io/) (company)
+  - [Chartbrew](https://github.com/chartbrew/chartbrew) (open source) / [Chartbrew](https://chartbrew.com/) (company)
+  - [Lightdash](https://github.com/lightdash/lightdash) (open source) / [Lightdash](https://www.lightdash.com/) (company)
+  - [CloudBeaver](https://github.com/dbeaver/cloudbeaver) (open source)
+  - [Awesome DB tools GUIs](https://github.com/mgramin/awesome-db-tools#gui)
+
+- Via https://github.com/crate/crate-clients-tools/issues
+  - [Looker](https://cloud.google.com/looker)
+  - [Metabase](https://github.com/metabase/metabase)
+  - [pgweb](https://sosedoff.github.io/pgweb/)
+  - [Redash](https://github.com/getredash/redash)
+  - [usql](https://github.com/xo/usql)
+
+- Re-evaluate
+  - Add [DataGrip]
+  - Add [pgAdmin]
+
+
+## Done
+- [x] CLI: Dedicated section per program, with code examples
+- [x] Connect: Improve "Configure" section about connection properties
+- [x] .NET driver got lost
+- [x] Remove DataGrip and pgAdmin again, they do not work
+
+
+[DataGrip]: https://www.jetbrains.com/datagrip/
+[HTTPie Desktop]: https://httpie.io/desktop
+[Info Card]: https://sphinx-design-elements.readthedocs.io/en/latest/infocard.html
+[pgAdmin]: https://www.pgadmin.org/

DEVELOP.rst

@@ -45,9 +45,9 @@ You must install `fswatch`_ to use the ``dev`` target.
 Continuous integration and deployment
 -------------------------------------
 
-|build| |travis| |rtd|
+|build| |gha| |rtd|
 
-Travis CI is `configured`_ to run ``make check`` from the ``docs`` directory.
+GHA is `configured`_ to run ``make check`` from the ``docs`` directory.
 Please do not merge pull requests until the tests pass.
 
 `Read the Docs`_ automatically deploys the documentation whenever a configured
@@ -58,21 +58,21 @@ release version), please contact the `@crate/tech-writing`_ team.
 
 
 .. _@crate/tech-writing: https://github.com/orgs/crate/teams/tech-writing
-.. _configured: https://github.com/crate/crate-clients-tools/blob/master/.travis.yml
+.. _configured: https://github.com/crate/crate-clients-tools/blob/main/.github/workflows/docs.yml
 .. _fswatch: https://github.com/emcrisostomo/fswatch
 .. _Read the Docs: http://readthedocs.org
 .. _ReStructuredText: http://docutils.sourceforge.net/rst.html
 .. _Sphinx: http://sphinx-doc.org/
 
 
-.. |build| image:: https://img.shields.io/endpoint.svg?color=blue&url=https%3A%2F%2Fraw.githubusercontent.com%2Fcrate%2Fcrate-clients-toolss%2Fmaster%2Fdocs%2Fbuild.json
+.. |build| image:: https://img.shields.io/endpoint.svg?color=blue&url=https%3A%2F%2Fraw.githubusercontent.com%2Fcrate%2Fcrate-clients-toolss%2Fmain%2Fdocs%2Fbuild.json
     :alt: Build version
-    :target: https://github.com/crate/crate-clients-tools/blob/master/docs/build.json
+    :target: https://github.com/crate/crate-clients-tools/blob/main/docs/build.json
 
-.. |travis| image:: https://img.shields.io/travis/crate/crate-clients-tools.svg?style=flat
+.. |gha| image:: https://github.com/crate/crate-clients-tools/actions/workflows/docs.yml/badge.svg
     :alt: Travis CI status
     :scale: 100%
-    :target: https://travis-ci.org/crate/crate-clients-tools
+    :target: https://github.com/crate/crate-clients-tools/actions/workflows/docs.yml
 
 .. |rtd| image:: https://readthedocs.org/projects/crate-clients-tools/badge/?version=latest
     :alt: Read The Docs status

LICENSE

@@ -175,28 +175,3 @@
       of your accepting any such warranty or additional liability.
 
    END OF TERMS AND CONDITIONS
-
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-   Copyright [yyyy] [name of copyright owner]
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.

MAINTAINERS.rst

@@ -0,0 +1,67 @@
+###########
+Maintainers
+###########
+
+
+About
+=====
+
+At Crate.io we are defining so called Power Users to ensure the integrations
+keep working.
+
+Responsibilities of Power Users:
+
+* Keep track of releases, updates and developments of the tools.
+* Test integration after minor and mayor CrateDB releases.
+* Test integration after tool releases.
+* Have a working setup available including a quick demo.
+* Being able to answer questions for the specific tool.
+* Ensuring guides are up to date.
+
+
+Power Users
+===========
+
++-----------------+-------------------+---------+-----------------+------------------------------------------------------+
+| Tool            | User              | Version | CrateDB Version |                                                      |
++=================+===================+=========+=================+======================================================+
+| Grafana         | `proddata`_       | *X.Y*   | *X.Y.Z*         | `Known Issues Grafana`_                              |
++-----------------+-------------------+---------+-----------------+------------------------------------------------------+
+| PowerBI         | `WolfgangHerbst`_ | *X.Y*   | *X.Y.Z*         | `Known Issues PowerBI`_                              |
++-----------------+-------------------+---------+-----------------+------------------------------------------------------+
+| Tableau         | `marregui`_       | *X.Y*   | *X.Y.Z*         | `Known Issues Tableau`_                              |
++-----------------+-------------------+---------+-----------------+------------------------------------------------------+
+| Zeppelin        |                   |         |                 |                                                      |
++-----------------+-------------------+---------+-----------------+------------------------------------------------------+
+| Looker          | `proddata`_       | *X.Y*   | *X.Y.Z*         | `Known Issues Looker`_                               |
++-----------------+-------------------+---------+-----------------+------------------------------------------------------+
+| Node-Red        | `proddata`_       | *X.Y*   | *X.Y.Z*         | `Known Issues Node Red`_                             |
++-----------------+-------------------+---------+-----------------+------------------------------------------------------+
+| NiFi            | `proddata`_       | *X.Y*   | *X.Y.Z*         | `Known Issues NiFi`_                                 |
++-----------------+-------------------+---------+-----------------+------------------------------------------------------+
+| Telegraf        |                   |         |                 |                                                      |
++-----------------+-------------------+---------+-----------------+------------------------------------------------------+
+| Prometheus      | `infoverload`_    | *X.Y*   | *X.Y.Z*         | `Known Issues Prometheus`_, `Known Issues Adapter`_  |
++-----------------+-------------------+---------+-----------------+------------------------------------------------------+
+| R               | `autophagy`_      | *X.Y*   | *X.Y.Z*         | `Known Issues R`_                                    |
++-----------------+-------------------+---------+-----------------+------------------------------------------------------+
+| Azure Functions | `autophagy`_      | *X.Y*   | *X.Y.Z*         | `Known Issues Azure Functions`_                      |
++-----------------+-------------------+---------+-----------------+------------------------------------------------------+
+
+
+.. _autophagy: https://github.com/autophagy
+.. _infoverload: https://github.com/infoverload
+.. _marregui: https://github.com/marregui
+.. _proddata: https://github.com/proddata
+.. _WolfgangHerbst: https://github.com/WolfgangHerbst
+
+.. _Known Issues Adapter: https://github.com/crate/crate_adapter/issues
+.. _Known Issues Azure Functions: https://github.com/crate/crate/labels/tool%3A%20Azure%20Functions
+.. _Known Issues Grafana: https://github.com/crate/crate/labels/tool%3A%20Grafana
+.. _Known Issues Looker: https://github.com/crate/crate/labels/tool%3A%20Looker
+.. _Known Issues NiFi: https://github.com/crate/crate/labels/tool%3A%20NiFi
+.. _Known Issues Node Red: https://github.com/crate/crate/labels/tool%3A%20Node-Red
+.. _Known Issues PowerBI: https://github.com/crate/crate/labels/tool%3A%20PowerBI
+.. _Known Issues Prometheus: https://github.com/crate/crate/labels/tool%3A%20Prometheus
+.. _Known Issues R: https://github.com/crate/crate/labels/tool%3A%20R
+.. _Known Issues Tableau: https://github.com/crate/crate/labels/tool%3A%20Tableau

README.rst

@@ -2,92 +2,31 @@
 CrateDB Clients and Tools
 =========================
 
-Clients and tools for working with `CrateDB`_.
-We are also maintaining a more up-to-date list of `CrateDB integration tutorials`_.
+Client libraries, applications, tools, and integrations for `CrateDB`_.
+We are also maintaining an up-to-date list of `CrateDB integration tutorials`_.
 
 Contributing
 ============
 
-This project is primarily maintained by `Crate.io`_, but we welcome community
-contributions!
-
-See the `developer docs`_ and the `contribution docs`_ for more information.
-
-
-Tool Power User
-===============
-
-At Crate.io we are defining so called Power Users to ensure the integrations
-keep working.
-
-Responsiblities of Power Users:
-
- * Keep track of releases, updates and developments of the tools.
- * Test integration after minor and mayor CrateDB releases.
- * Test integration after tool releases.
- * Have a working setup available including a quick demo.
- * Being able to answer questions for the specific tool.
- * Ensuring guides are up to date.
-
-
-Power Users
------------
-
-+-----------------+-------------------+---------+-----------------+------------------------------------------------------+
-| Tool            | User              | Version | CrateDB Version |                                                      |
-+=================+===================+=========+=================+======================================================+
-| Grafana         | `proddata`_       | *X.Y*   | *X.Y.Z*         | `Known Issues Grafana`_                              |
-+-----------------+-------------------+---------+-----------------+------------------------------------------------------+
-| PowerBI         | `WolfgangHerbst`_ | *X.Y*   | *X.Y.Z*         | `Known Issues PowerBI`_                              |
-+-----------------+-------------------+---------+-----------------+------------------------------------------------------+
-| Tableau         | `marregui`_       | *X.Y*   | *X.Y.Z*         | `Known Issues Tableau`_                              |
-+-----------------+-------------------+---------+-----------------+------------------------------------------------------+
-| Zeppelin        |                   |         |                 |                                                      |
-+-----------------+-------------------+---------+-----------------+------------------------------------------------------+
-| Looker          | `proddata`_       | *X.Y*   | *X.Y.Z*         | `Known Issues Looker`_                               |
-+-----------------+-------------------+---------+-----------------+------------------------------------------------------+
-| Node-Red        | `proddata`_       | *X.Y*   | *X.Y.Z*         | `Known Issues Node Red`_                             |
-+-----------------+-------------------+---------+-----------------+------------------------------------------------------+
-| NiFi            | `proddata`_       | *X.Y*   | *X.Y.Z*         | `Known Issues NiFi`_                                 |
-+-----------------+-------------------+---------+-----------------+------------------------------------------------------+
-| Telegraf        |                   |         |                 |                                                      |
-+-----------------+-------------------+---------+-----------------+------------------------------------------------------+
-| Prometheus      | `infoverload`_    | *X.Y*   | *X.Y.Z*         | `Known Issues Prometheus`_, `Known Issues Adapter`_  |
-+-----------------+-------------------+---------+-----------------+------------------------------------------------------+
-| R               | `autophagy`_      | *X.Y*   | *X.Y.Z*         | `Known Issues R`_                                    |
-+-----------------+-------------------+---------+-----------------+------------------------------------------------------+
-| Azure Functions | `autophagy`_      | *X.Y*   | *X.Y.Z*         | `Known Issues Azure Functions`_                      |
-+-----------------+-------------------+---------+-----------------+------------------------------------------------------+
-
+This project is primarily maintained by `Crate.io`_, and community contributions
+are welcome. See the `developer docs`_ and the `contribution docs`_ for more
+information.
 
 Help
 ====
 
-Looking for more help?
+Looking for help?
 
 - Read the `live docs`_
 - Check out our `support channels`_
+- Visit the `community forum`_
 
 
-.. _autophagy: https://github.com/autophagy
 .. _contribution docs: CONTRIBUTING.rst
+.. _community forum: https://community.crate.io/
 .. _Crate.io: http://crate.io/
 .. _CrateDB: https://crate.io/products/cratedb/
 .. _CrateDB integration tutorials: https://community.crate.io/t/overview-of-cratedb-integration-tutorials/1015
 .. _developer docs: DEVELOP.rst
-.. _infoverload: https://github.com/infoverload
-.. _Known Issues Adapter: https://github.com/crate/crate_adapter/issues
-.. _Known Issues Azure Functions: https://github.com/crate/crate/labels/tool%3A%20Azure%20Functions
-.. _Known Issues Grafana: https://github.com/crate/crate/labels/tool%3A%20Grafana
-.. _Known Issues Looker: https://github.com/crate/crate/labels/tool%3A%20Looker
-.. _Known Issues NiFi: https://github.com/crate/crate/labels/tool%3A%20NiFi
-.. _Known Issues Node Red: https://github.com/crate/crate/labels/tool%3A%20Node-Red
-.. _Known Issues PowerBI: https://github.com/crate/crate/labels/tool%3A%20PowerBI
-.. _Known Issues Prometheus: https://github.com/crate/crate/labels/tool%3A%20Prometheus
-.. _Known Issues R: https://github.com/crate/crate/labels/tool%3A%20R
-.. _Known Issues Tableau: https://github.com/crate/crate/labels/tool%3A%20Tableau
 .. _live docs: https://crate.io/docs/crate/clients-tools/en/latest/
-.. _marregui: https://github.com/marregui
-.. _proddata: https://github.com/proddata
 .. _support channels: https://crate.io/support/
-.. _WolfgangHerbst: https://github.com/WolfgangHerbst