lidavidm commented on code in PR #4525:
URL: https://github.com/apache/arrow-adbc/pull/4525#discussion_r3583757945
##########
docs/source/index.rst:
##########
@@ -40,190 +40,264 @@ Apache Arrow ADBC
**Cross-language**, **Arrow-native** database access.
ADBC is a set of APIs and libraries for Arrow-native access to databases.
-Execute SQL and Substrait_ queries, query database catalogs, and more, all
+Execute SQL queries, insert bulk data, query database catalogs, and more, all
using Arrow data to eliminate unnecessary data copies, speed up access, and
make it more convenient to build analytical applications.
+Getting Started
+---------------
+
+.. grid:: 1 1 2 3
+ :gutter: 3
+
+ .. grid-item-card:: :octicon:`plug` Available Drivers
+ :link: driver/index
+ :link-type: doc
+
+ Connect to a growing list of databases using ADBC drivers.
+
+ .. grid-item-card:: :octicon:`code` Client Libraries
+ :link: client_libraries
+ :link-type: doc
+
+ Use ADBC from C/C++, C#, Go, Java, JavaScript, Python, R, Ruby, and Rust.
+
+ .. grid-item-card:: :octicon:`tools` Building Drivers
+ :link: driver/authoring
+ :link-type: doc
+
+ Build your own ADBC driver using the driver SDKs available in multiple
languages.
+
+
+.. _dbc: https://docs.columnar.tech/dbc
.. _Substrait: https://substrait.io/
-.. div::
+Why ADBC?
+---------
- .. grid::
- :margin: 4 4 0 0
- :gutter: 1
+.. grid:: 1 2 2 2
+ :margin: 4 4 0 0
+ :gutter: 1
- .. grid-item-card::
- :columns: 12 12 4 4
+ .. grid-item-card:: Arrow-native
+ :link: https://arrow.apache.org/
- Quickstart
- ^^^
+ Execute queries and get back results in Arrow format, eliminating extra
+ data copies for Arrow-native backends.
- Get started with simple examples in your language of choice.
+ +++
+ Learn about Apache Arrow
- +++
+ .. grid-item-card:: Backend-agnostic
+ :link: driver/status
+ :link-type: doc
- .. button-ref:: cpp/quickstart
- :ref-type: doc
- :color: secondary
- :expand:
+ Connect to all kinds of databases, even ones that aren't Arrow-native.
+ ADBC drivers optimize conversion to/from Arrow where required, saving
+ work for developers.
+
+ +++
+ See Supported Drivers
- C/C++
+ .. grid-item-card:: Cross-language
- .. button-link::
https://pkg.go.dev/github.com/apache/arrow-adbc/go/adbc
- :color: secondary
- :expand:
+ Work in C/C++, C#, Go, Java, Python, R, Ruby, Rust, and more.
- Go
+ .. grid-item-card:: Full-featured
- .. button-ref:: java/quickstart
- :ref-type: doc
- :color: secondary
- :expand:
+ Execute SQL and Substrait, query database catalogs, inspect table
+ schemas, and more. ADBC handles common tasks without having to pull in
+ another database client.
- Java
+ .. grid-item-card:: Language-native
- .. button-ref:: javascript/index
- :ref-type: doc
- :color: secondary
- :expand:
+ Use language-native APIs that you're already familiar with, like DBAPI
+ in Python, ``database/sql`` in Go, or DBI in R.
- JavaScript
+More Resources
+--------------
- .. button-ref:: python/quickstart
- :ref-type: doc
- :color: secondary
- :expand:
+.. grid:: 1 2 2 2
+ :margin: 4 4 0 0
+ :gutter: 1
- Python
+ .. grid-item-card:: Examples & Tutorials
+ :link: https://github.com/columnar-tech/adbc-quickstarts
- .. button-ref:: r/index
- :ref-type: doc
- :color: secondary
- :expand:
+ Working examples and tutorials for multiple languages and databases in
the `adbc-quickstarts repository
<https://github.com/columnar-tech/adbc-quickstarts>`_.
- R
+ +++
+ :octicon:`cross-reference` View on GitHub
- .. button-ref:: rust/quickstart
- :ref-type: doc
- :color: secondary
- :expand:
+ .. grid-item-card:: Tools & Integrations
+
+ Learn how ADBC works with popular data tools and frameworks.
+
+ +++
+ :doc:`integrations`
+
+ .. grid-item-card:: Building Drivers
- Rust
+ Learn how to build your own ADBC driver.
- .. grid-item-card::
- :columns: 12 4 4 4
+ +++
+ :doc:`driver/authoring`
+
+ .. grid-item-card:: Specification
+
+ Technical specification of the ADBC API.
+
+ +++
+ :doc:`format/specification`
+
+Old Content
+-----------
+
+(TODO: Rework this)
+
+.. grid:: 1 2 3 4
+ :margin: 4 4 0 0
+ :gutter: 2
- Specification
- ^^^
+ .. grid-item-card::
+ :columns: 12 4 4 4
- Learn about the underlying API specification.
+ Connect
+ ^^^^^^^
- +++
+ Connect to many different databases with ADBC using your language(s) of
choice.
- .. button-link::
https://arrow.apache.org/blog/2023/01/05/introducing-arrow-adbc/
+ +++
+
+ .. button-ref:: client_libraries
+ :ref-type: doc
:color: secondary
:expand:
- Introducing ADBC :octicon:`cross-reference`
+ Client Libraries
- .. button-ref:: format/specification
+ .. button-ref:: driver/index
:ref-type: doc
:color: secondary
:expand:
- Specification
+ Drivers
- .. button-ref:: faq
+ .. button-ref:: integrations
:ref-type: doc
:color: secondary
:expand:
- FAQ
+ Tools & Integrations
- .. button-ref:: glossary
+ .. button-ref:: connection_profiles
:ref-type: doc
:color: secondary
:expand:
- Glossary
+ Connection Profiles
- .. grid-item-card::
- :columns: 12 4 4 4
+ .. grid-item-card::
+ :columns: 12 4 4 4
- Development
- ^^^
+ Build
+ ^^^^^
- Report bugs, ask questions, and contribute to Apache Arrow.
+ Learn how ADBC drivers are built and learn how to build your own.
- +++
+ +++
- .. button-link:: https://github.com/apache/arrow-adbc/issues
+ .. button-ref:: driver/authoring
+ :ref-type: doc
:color: secondary
:expand:
- :fab:`github` Issues/Questions
+ Writing New Drivers
- .. button-link:: https://arrow.apache.org/community/
- :color: secondary
- :expand:
+ .. button-ref:: format/specification
+ :ref-type: doc
+ :color: secondary
+ :expand:
- Mailing List :octicon:`cross-reference`
+ ADBC Specification
- .. button-link::
https://github.com/apache/arrow-adbc/blob/main/CONTRIBUTING.md
- :color: secondary
- :expand:
+ .. grid-item-card::
+ :columns: 12 4 4 4
- Contributing :octicon:`cross-reference`
+ Learn
+ ^^^^^
-Why ADBC?
-=========
+ Learn more about ADBC.
-.. grid:: 1 2 2 2
- :margin: 4 4 0 0
- :gutter: 1
+ +++
- .. grid-item-card:: Arrow-native
- :link: https://arrow.apache.org/
+ .. button-link::
https://arrow.apache.org/blog/2023/01/05/introducing-arrow-adbc/
+ :color: secondary
+ :expand:
- Execute queries and get back results in Arrow format, eliminating extra
- data copies for Arrow-native backends.
+ Introducing ADBC :octicon:`cross-reference`
- +++
- Learn about Apache Arrow
+ .. button-ref:: faq
+ :ref-type: doc
+ :color: secondary
+ :expand:
- .. grid-item-card:: Backend-agnostic
- :link: driver/status
- :link-type: doc
+ FAQ
- Connect to all kinds of databases, even ones that aren't Arrow-native.
- ADBC drivers optimize conversion to/from Arrow where required, saving
- work for developers.
+ .. button-ref:: glossary
+ :ref-type: doc
+ :color: secondary
+ :expand:
+
+ Glossary
+
+ .. grid-item-card::
+ :columns: 12 4 4 4
+
+ Development
+ ^^^^^^^^^^^
+
+ Report bugs, ask questions, and contribute to Apache Arrow.
+++
- See Supported Drivers
- .. grid-item-card:: Cross-language
+ .. button-link:: https://github.com/apache/arrow-adbc/issues
+ :color: secondary
+ :expand:
- Work in C/C++, C#, Go, Java, Python, R, Ruby, Rust, and more.
+ :fab:`github` Issues/Questions
- .. grid-item-card:: Full-featured
+ .. button-link:: https://arrow.apache.org/community/
+ :color: secondary
+ :expand:
- Execute SQL and Substrait, query database catalogs, inspect table
- schemas, and more. ADBC handles common tasks without having to pull in
- another database client.
+ Mailing List :octicon:`cross-reference`
- .. grid-item-card:: Language-native
+ .. button-link::
https://github.com/apache/arrow-adbc/blob/main/CONTRIBUTING.md
+ :color: secondary
+ :expand:
- Use language-native APIs that you're already familiar with, like DBAPI
- in Python, ``database/sql`` in Go, or DBI in R.
+ Contributing :octicon:`cross-reference`
.. toctree::
:maxdepth: 1
+ :caption: Connect
:hidden:
- faq
- glossary
- genindex
+ Client Libraries <client_libraries>
+ Drivers <driver/index>
+ Drivers (Cards View) <driver/alt1>
+ Drivers (Database Sections) <driver/alt2>
+ Tools & Integrations <integrations>
+ Connection Profiles <connection_profiles>
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Build
+ :hidden:
+
+ Writing New Drivers <driver/authoring>
+ Driver Manifests <format/driver_manifests>
Review Comment:
Does this really go here?
##########
docs/source/connection_profiles.rst:
##########
Review Comment:
I think if this is intended to be a user-friendly page it should introduce
an example of a profile as well
##########
docs/source/driver/authoring.rst:
##########
@@ -19,20 +19,33 @@
Writing New Drivers
===================
-Currently, new drivers can be written in C#, C/C++, Go, and Java. A driver
-written in C/C++ or Go can be used from either of those languages, as well as
-C#, Python, R, and Ruby. (C# can experimentally export drivers to the same
-set of languages as well.) The Rust API definitions for ADBC are still under
-development, but we plan for them to be on par with C#, C/C++, and Go in this
-respect.
+ADBC drivers can be written in C/C++, C#, Go, Java, or Rust.
+Because drivers expose a :doc:`standard C ABI <../format/specification>`, a
driver written in any of these languages can be used from client libraries in
any other language, so the implementation language is largely a matter of
ecosystem fit and preference.
-It is so far preferable to write new drivers in Go. C/C++ have had issues
-with dependencies and in particular some not uncommon dependencies in that
-ecosystem tend to cause conflicts when loaded into Python processes and
-elsewhere. (For example, the ADBC Flight SQL driver was originally written in
-C++ but would have conflicted with the grpcio and pyarrow Python packages.)
-It also tends to be easier for us to package and distribute additional Go
-libraries than it is for C/C++.
+.. list-table::
+ :header-rows: 1
+
+ * - Language
+ - Documentation
+ - Notes
+ * - C/C++
+ - :doc:`../cpp/index`
+ - Drivers are loadable by the Driver Manager and usable from all client
languages.
+ * - C#
+ - :doc:`../csharp/index`
+ - Can experimentally export drivers for use from other languages via the
C ABI.
+ * - Go
+ - `go/adbc <https://pkg.go.dev/github.com/apache/arrow-adbc/go/adbc>`__
+ - Recommended for new drivers; easiest to package and distribute. Drivers
are loadable by the Driver Manager and usable from all client languages.
+ * - Java
+ - :doc:`../java/index`
+ - Drivers are usable from Java client libraries.
+ * - Rust
+ - :doc:`../rust/quickstart`
+ - API definitions are still maturing. Drivers can be compiled to a C ABI
shared library for use from other languages.
+
+Go is generally the recommended choice for new drivers.
Review Comment:
```suggestion
Go and Rust are generally the recommended choice for new drivers.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
