Repository navigation
Add the embedded Python bindings (arcadedb-embedded) to the docs #502
Description
We are moving the Python bindings (arcadedb-embedded, import name arcadedb_embedded) into ArcadeData/arcadedb-python-bindings. Their docs are Markdown for MkDocs today (about 107 files, 25k lines) and are hosted outside this site. We would like the user-facing part to live here, in your Antora/AsciiDoc tree, so there is one docs site. This issue proposes where the pages go before we send anything big.
Where it goes. The existing Python group in the Languages & Drivers nav gets one more entry, "Embedded bindings", next to the native HTTP and gRPC drivers. Pages follow the tutorial / how-to / reference split from the native-drivers design spec:
| Kind | Page | From our docs |
|---|---|---|
| how-to | how-to/connectivity/python-embedded.adoc: install, open a database, query, embedded vs HTTP driver |
installation, access methods, index |
| tutorial | tutorials/python-embedded-quickstart.adoc |
quickstart |
| how-to | how-to/python-embedded/ with one page each: databases and queries, transactions, graphs, graph analytics, vectors, time series, data import, server mode, JVM and logging, known engine issues |
the guide section (12 files, about 4.7k lines) |
| how-to | 5 or 6 short worked examples, picked from our 28 | examples |
| reference | reference/python-api/: one page per area (database, transactions, results, vector, importer, and so on) |
the API section (14 files) |
Not moved: development (build, release, CI, upstream sync), the benchmark protocol pages, and the long benchmark-style examples. They stay as Markdown in the bindings repo.
API reference. Antora has no Python autodoc. Our current reference is hand-written Markdown, which is a lot of text to keep in step with the code. We propose to generate AsciiDoc from the docstrings in the bindings repo CI, and open a PR here on each release that updates reference/python-api/. Generated pages are marked as generated. The alternative is a short hand-written reference page that links to the repository.
Question for you. Are you fine with generated .adoc files being committed here by a release PR, or do you prefer the generated reference to be built from the bindings repo at site build time, or kept hand-written and short? We will do whichever you choose.
Plan. Small PRs, one page or one group each. The first one is open: it adds the embedded bindings to the Python quickstart's connection-options box, and one new how-to page linked from Languages & Drivers and the nav. Every claim on it comes from the bindings' own docs, and the code samples were run on the published arcadedb-embedded wheel. We will follow the repo conventions (lowercase-hyphen file names and anchors, docs-validator.py, the generate-nav.py entry).
While here: the quickstart's "Embedded Python Bindings" section links to our old repository. The first PR repoints it to the new page. Tracking on our side: ArcadeData/arcadedb-python#19.
Activity
tae898 commentedon Oct 23, 2026
One more question on where the rest goes. The bindings have their own release numbers (26.10.2.post1 next to engine 26.10.2) and will have a generated API reference, so I would suggest a separate Antora component,
arcadedb-python, published at docs.arcadedb.com/arcadedb-python/ with its own nav and versions, while the how-to page in #503 stays in the main component as the entry point. Its AsciiDoc would live in ArcadeData/arcadedb-python underdocs/, next to the code, and the playbook here would add it as a second content source (one more entry undercontent.sources), so the site, theme and search stay one. The alternative is to append everything to thearcadedbcomponent in this repo, which keeps one place to edit but ties the bindings pages to the engine versions. Which do you prefer? We can send the playbook change and the docs scaffold either way.