Skip to content

Commit

Permalink
Automatically update API docs on release (#579)
Browse files Browse the repository at this point in the history
- Use Quarto documentation
- Autobuild docs, using quartodoc
    - on PRs, 
    - merges to main 
    - publish them on release.
  • Loading branch information
JohnMoutafis authored Jun 10, 2024
1 parent e57ed9b commit 48ef583
Show file tree
Hide file tree
Showing 16 changed files with 334 additions and 287 deletions.
64 changes: 64 additions & 0 deletions .github/workflows/publish_docs.yaml
Original file line number Diff line number Diff line change
@@ -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 }}
11 changes: 11 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
10 changes: 6 additions & 4 deletions docs/.gitignore
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
/.quarto/
_build
_static
#_templates
build
_autosummary
reference

# interlinks
objects.json
_sidebar.yml
20 changes: 0 additions & 20 deletions docs/Makefile

This file was deleted.

Binary file added docs/TileDB_logo_primary.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
192 changes: 192 additions & 0 deletions docs/_quarto.yaml
Original file line number Diff line number Diff line change
@@ -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
35 changes: 35 additions & 0 deletions docs/get_started.qmd
Original file line number Diff line number Diff line change
@@ -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>
)
```
25 changes: 25 additions & 0 deletions docs/index.qmd
Original file line number Diff line number Diff line change
@@ -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]
```
Loading

0 comments on commit 48ef583

Please sign in to comment.