Automatically update API docs on release (#579)

- Use Quarto documentation
- Autobuild docs, using quartodoc
    - on PRs, 
    - merges to main 
    - publish them on release.

.github/workflows/publish_docs.yaml

@@ -0,0 +1,64 @@
+name: Build Documentation
+
+on:
+  workflow_dispatch:
+  pull_request:
+  push:
+    branches:
+      - main
+  release:
+    types:
+      - created
+
+permissions:
+  contents: write
+  pages: write
+
+jobs:
+  build-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Quarto
+        uses: quarto-dev/quarto-actions/setup@v2
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up Python 3.9
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.9"
+
+      - name: Install prerequisites
+        run: |
+          pip install --upgrade \
+            pip \
+            wheel \
+            setuptools \
+            setuptools-scm
+
+      - name: Install TileDB-Cloud-Py with doc dependencies
+        run: |
+          pip install .[docs]
+
+      - name: Qartodoc Build
+        run: |
+          quartodoc build --config docs/_quarto.yaml
+
+      - name: Render Docs
+        uses: quarto-dev/quarto-actions/render@v2
+        with:
+          path: docs/
+
+      # Publish Docs only when a new release is created
+      - name: Publish Rendered Docs
+        if: github.event_name == 'release'
+        uses: quarto-dev/quarto-actions/publish@v2
+        with:
+          target: gh-pages
+          path: docs/
+          render: false
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

README.md

@@ -16,6 +16,17 @@ See [Quickstart](https://docs.tiledb.com/cloud/quickstart) section of the docs.
 
 See https://tiledb-inc.github.io/TileDB-Cloud-Py/
 
+#### Contribute to documentation
+
+Documentation uses [Quarto](https://quarto.org/) style documentation.
+
+- Install [Quarto for your OS](https://quarto.org/docs/get-started/)
+- Install documentation dependencies: `pip install .[docs]`
+- Update the [docs/\_quarto.yaml](docs/_quarto.yaml) file accordingly ([read the quartodoc documentation on how to do that](https://quarto.org/docs/get-started/))
+- Build the docs: `quartodoc build --config docs/_quarto.yaml`
+- Preview the generated docs: `quarto preview docs/`
+- Create a relevant PR
+
 ### Testing
 
 - Selection:

docs/.gitignore

@@ -1,5 +1,7 @@
+/.quarto/
 _build
-_static
-#_templates
-build
-_autosummary
+reference
+
+# interlinks
+objects.json
+_sidebar.yml

docs/_quarto.yaml

@@ -0,0 +1,192 @@
+project:
+  type: website
+  output-dir: _build
+
+website:
+  # title: "Cloud-Py"
+  description: "TileDB's Cloud Client for Python"
+  repo-url: https://github.com/TileDB-Inc/TileDB-Cloud-Py/
+  favicon: "t_favicon.png"
+  page-navigation: true
+  navbar:
+    background: light
+    logo: "TileDB_logo_primary.png"
+    pinned: true
+    left:
+      - text: Get Started
+        file: get_started.qmd
+      - text: API
+        file: reference/index.qmd
+
+  sidebar:
+    style: "floating"
+    collapse-level: 1
+    contents:
+      - Cloud-Py
+      - section: Cloud Services
+        contents:
+          - text: "`array`"
+            href: reference/array.qmd
+          - text: "`asset`"
+            href: reference/asset.qmd
+          - text: "`client`"
+            href: reference/client.qmd
+          - text: "`cloudarray`"
+            href: reference/cloudarray.qmd
+          - text: "`config`"
+            href: reference/config.qmd
+          - text: "`file`"
+            href: reference/file.qmd
+          - text: "`groups`"
+            href: reference/groups.qmd
+          - text: "`invites`"
+            href: reference/invites.qmd
+          - text: "`notebook`"
+            href: reference/notebook.qmd
+          - text: "`pool_manager_wrapper`"
+            href: reference/pool_manager_wrapper.qmd
+          - text: "`tasks`"
+            href: reference/tasks.qmd
+          - text: "`tiledb_cloud_error`"
+            href: reference/tiledb_cloud_error.qmd
+          - text: "`udf`"
+            href: reference/udf.qmd
+          - text: "`utils`"
+            href: reference/utils.qmd
+      - section: Bio-Imaging
+        contents:
+          - text: "`exportation`"
+            href: reference/bioimg.exportation.qmd
+          - text: "`helpers`"
+            href: reference/bioimg.helpers.qmd
+          - text: "`ingestion`"
+            href: reference/bioimg.ingestion.qmd
+      - section: Compute
+        contents:
+          - text: "`delayed`"
+            href: reference/compute.delayed.qmd
+      - section: DAG
+        contents:
+          - text: "`dag`"
+            href: reference/dag.dag.qmd
+          - text: "`mode`"
+            href: reference/dag.mode.qmd
+          - text: "`status`"
+            href: reference/dag.status.qmd
+          - text: "`visualization`"
+            href: reference/dag.visualization.qmd
+      - section: Files
+        contents:
+          - text: "`indexing`"
+            href: reference/files.indexing.qmd
+          - text: "`ingestion`"
+            href: reference/files.ingestion.qmd
+          - text: "`udfs`"
+            href: reference/files.udfs.qmd
+          - text: "`utils`"
+            href: reference/files.utils.qmd
+      - section: Geospatial
+        contents:
+          - text: "`ingestion`"
+            href: reference/geospatial.ingestion.qmd
+      - section: SOMA
+        contents:
+          - text: "`ingest`"
+            href: reference/soma.ingest.qmd
+          - text: "`mapper`"
+            href: reference/soma.mapper.qmd
+      - section: VCF
+        contents:
+          - text: "`allele_frequency`"
+            href: reference/vcf.allele_frequency.qmd
+          - text: "`ingestion`"
+            href: reference/vcf.ingestion.qmd
+          - text: "`query`"
+            href: reference/vcf.query.qmd
+          - text: "`utils`"
+            href: reference/vcf.utils.qmd
+      - section: Utilities
+        contents:
+          - text: "`consolidate`"
+            href: reference/utilities.consolidate.qmd
+          - text: "`profiler`"
+            href: reference/utilities.profiler.qmd
+
+quartodoc:
+  style: pkgdown
+  parser: sphinx
+  package: tiledb.cloud
+  title: API Reference
+
+  sections:
+    - title: Cloud Services
+      desc: Cloud Interaction Services
+      contents:
+        - array
+        - asset
+        - client
+        - cloudarray
+        - config
+        - file
+        - groups
+        - invites
+        - notebook
+        - pool_manager_wrapper
+        - tasks
+        - tiledb_cloud_error
+        - udf
+        - utils
+
+    - title: bioimg
+      desc: Bio imaging API
+      contents:
+        - bioimg.exportation
+        - bioimg.helpers
+        - bioimg.ingestion
+
+    - title: compute
+      desc: Compute API
+      contents:
+        - compute.delayed
+
+    - title: dag
+      desc: DAG API
+      contents:
+        - dag.dag
+        - dag.mode
+        - dag.status
+        - dag.visualization
+
+    - title: files
+      desc: File API.
+      contents:
+        - files.indexing
+        - files.ingestion
+        - files.udfs
+        - files.utils
+
+    - title: geospatial
+      desc: Geospatial API
+      contents:
+        - geospatial.ingestion
+
+    - title: soma
+      desc: SOMA API
+      contents:
+        - soma.ingest
+        - soma.mapper
+
+    - title: vcf
+      desc: VCF API
+      contents:
+        - vcf.allele_frequency
+        - vcf.ingestion
+        - vcf.query
+        - vcf.utils
+
+    - title: utilities
+      desc: Common Utilities API
+      contents:
+        - utilities.consolidate
+        - utilities.profiler
+        # - wheel

docs/get_started.qmd

@@ -0,0 +1,35 @@
+---
+title: Get started with TileDB Cloud for Python
+---
+
+This is a starting guide for the TileDB-Cloud-Py client.<br/>
+
+# Login
+
+To login programmatically you will need either
+
+- Username and Password [of your TileDB account](https://cloud.tiledb.com/).
+- Or an API Token [generated from your TileDB account](https://docs.tiledb.com/cloud/how-to/account/create-api-tokens).
+
+## Username and Password method
+
+```python
+import tiledb.cloud
+
+tiledb.cloud.login(
+    host=<tiledb.host>,
+    username=<username>,
+    password=<password>
+)
+```
+
+## Token method
+
+```python
+import tiledb.cloud
+
+tiledb.cloud.login(
+    host=<tiledb.host>,
+    token=<token>
+)
+```

docs/index.qmd

@@ -0,0 +1,25 @@
+# Cloud-Py <a href="https://github.com/TileDB-Inc/TileDB-Cloud-Py/"><img src="TileDB_logo_primary.png" align="right" height="50"></a>
+
+Welcome to TileDB's Cloud [Python client](https://github.com/TileDB-Inc/TileDB-Cloud-Py/).<br>
+This client offers programmatic access to [TileDB Cloud](https://docs.tiledb.com/cloud).
+
+# Installation
+
+You can install the Cloud-Py SDK client as follows:
+
+```python
+pip install tiledb-cloud
+```
+
+While the preferred method of running code samples and notebooks in this section is directly within TileDB Cloud (as all dependencies are installed for you), you can run most of the code samples and notebooks in this section locally. To run these code samples and notebooks locally, install the following dependencies:
+
+```python
+pip install ipykernel jupyterlab graphviz
+pip install tiledb-cloud[all]
+```
+
+For Life Science capabilities:
+
+```python
+pip install tiledb-cloud[life-sciences]
+```