You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@arrow.apache.org by "lidavidm (via GitHub)" <gi...@apache.org> on 2024/08/19 12:13:47 UTC
[I] docs: improve cookbook Sphinx tag [arrow-adbc]
lidavidm opened a new issue, #2082:
URL: https://github.com/apache/arrow-adbc/issues/2082
### What feature or improvement would you like to see?
- Add an index of all recipes
- Add an ID to each recipe that can be linked to
- Add title/short description/driver/tags to each recipe for the index's use (e.g. we can generate index pages for each language and tag and driver)
- Highlight the cookbook examples more strongly on the home page
- e.g. link directly to language or driver examples
- add a carousel showcasing some common tasks
Strawman:
```python
# Use ADBC PostgreSQL with SQLAlchemy
# postgresql, sqlalchemy
#
# Build queries with SQLAlchemy, then submit them via ADBC.
# RECIPE BEGINS HERE
import ...
```
--
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: issues-unsubscribe@arrow.apache.org.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] docs: improve cookbook Sphinx tag [arrow-adbc]
Posted by "lidavidm (via GitHub)" <gi...@apache.org>.
lidavidm commented on issue #2082:
URL: https://github.com/apache/arrow-adbc/issues/2082#issuecomment-2624132783
Draft PR up at https://github.com/apache/arrow-adbc/pull/2495
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] docs: improve cookbook Sphinx tag [arrow-adbc]
Posted by "lidavidm (via GitHub)" <gi...@apache.org>.
lidavidm commented on issue #2082:
URL: https://github.com/apache/arrow-adbc/issues/2082#issuecomment-2298070645
Another thing we could do:
- Index all recipes based on scanning .py files in the source tree
- Provide directives to insert particular recipes or list all recipes based on tags
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] docs: improve cookbook Sphinx tag [arrow-adbc]
Posted by "amoeba (via GitHub)" <gi...@apache.org>.
amoeba commented on issue #2082:
URL: https://github.com/apache/arrow-adbc/issues/2082#issuecomment-2624910715
I think that could work and covers the two gaps I mentioned above. I have a test repo for the cookbooks and I'll give the new version a try and let you know.
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] docs: improve cookbook Sphinx tag [arrow-adbc]
Posted by "lidavidm (via GitHub)" <gi...@apache.org>.
lidavidm closed issue #2082: docs: improve cookbook Sphinx tag
URL: https://github.com/apache/arrow-adbc/issues/2082
--
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: issues-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] docs: improve cookbook Sphinx tag [arrow-adbc]
Posted by "lidavidm (via GitHub)" <gi...@apache.org>.
lidavidm commented on issue #2082:
URL: https://github.com/apache/arrow-adbc/issues/2082#issuecomment-2620861748
@amoeba since we talked about supporting stdout/stderr, what do you think of this? Initially I had the stdout inline with the prose but decided it broke things up too much so I consolidated it to the end.
For testing, I'm thinking I can add a CLI and/or pre-commit check that parses all the recipes and dumps stdout/stderr to text files alongside the source file. That can then be loaded and checked by some test harness. (Saves them from all having to parse the recipe source.)
<details>
<summary>Recipe source</summary>
```python
# RECIPE STARTS HERE
#: To connect to a PostgreSQL database, the username and password must
#: be provided in the URI. For example,
#:
#: .. code-block:: text
#:
#: postgresql://username:password@hostname:port/dbname
#:
#: See the `PostgreSQL documentation
#: <https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING>`_
#: for full details.
import os
import adbc_driver_postgresql.dbapi
uri = os.environ["ADBC_POSTGRESQL_TEST_URI"]
conn = adbc_driver_postgresql.dbapi.connect(uri)
with conn.cursor() as cur:
cur.execute("SELECT 1")
print(cur.fetchone())
# STDOUT: (1,)
conn.close()
```
</details>
<details>
<summary>Rendered output</summary>
</details>
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] docs: improve cookbook Sphinx tag [arrow-adbc]
Posted by "lidavidm (via GitHub)" <gi...@apache.org>.
lidavidm commented on issue #2082:
URL: https://github.com/apache/arrow-adbc/issues/2082#issuecomment-2296464507
I am leaning towards "YAML frontmatter" though just because it is easily parseable. Though perhaps even better would be a docstring
```python
"""
Build queries with SQLAlchemy, then submit them via ADBC.
Tags
----
postgresql, sqlalchemy
"""
```
A separate title seems redundant as well here
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] docs: improve cookbook Sphinx tag [arrow-adbc]
Posted by "lidavidm (via GitHub)" <gi...@apache.org>.
lidavidm commented on issue #2082:
URL: https://github.com/apache/arrow-adbc/issues/2082#issuecomment-2620895700
The other thing I've figured out is how to get Sphinx to generate index entries like this:
Hopefully making it easier to go from task -> driver-specific recipe and driver -> task recipes
--
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: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org