Update in-repo docs (#525)

Makefile

@@ -37,6 +37,18 @@ test:
 	pytest apis/python
 	python -c "import tiledbvcf; print(tiledbvcf.version)"
 
+# docs
+# -------------------------------------------------------------------
+.PHONY: notebooks
+notebooks:
+	@for f in `find examples -name "*.ipynb"`; do \
+		jupyter nbconvert --execute --to=notebook --inplace $$f; \
+	done
+
+.PHONY: docs
+docs:
+	quarto render --fail-if-warnings
+
 # format
 # -------------------------------------------------------------------
 .PHONY: check-format
@@ -69,6 +81,8 @@ Rules:
   install [options]   Build C++ library and install python module
   update              Incrementally build C++ library and update python module
   test                Run tests
+  notebooks           Execute notebooks and update cell outputs
+  docs                Render the documentation
   check-format        Run C++ format check
   format              Run C++ format
   clean               Remove build artifacts

_quarto.yml

@@ -7,6 +7,7 @@ project:
     - "documentation/index.md"
     - "documentation"
     - "examples/README.md"
+    - "examples"
 
 format:
   html:
@@ -50,6 +51,10 @@ website:
 
         - section:
           href: "examples/README.md"
+          contents:
+            - href: "examples/tutorial_tiledbvcf_basics.ipynb"
+            - href: "examples/tutorial_tiledbvcf_allele_frequencies.ipynb"
+            - href: "examples/tutorial_tiledbvcf_gwas.ipynb"
 
         - section:
           href: "documentation/ingestion/overview.md"

documentation/README.md

@@ -0,0 +1,31 @@
+# Quarto Documentation
+
+This directory contains the source for the Quarto documentation. The documentation is built using the [Quarto](https://quarto.org) document format and toolchain.
+
+
+## Execute Notebooks
+
+> **NOTE** - Executing the example notebooks is not required to render the documentation. Rendering will use the pre-rendered notebook outputs in the `examples` directory.
+
+Jupyter notebooks are located in the `examples` directory in the root of the repository. 
+
+Executing the notebooks requires a Python environment with all notebook dependencies installed. Run the following command to add the notebook dependencies to an existing `tiledbvcf-py` Python environment:
+
+```
+pip install -r requirements-doc.txt
+```
+
+Run the following command from the root of the repository to execute the example notebooks and update the contents of the notebook cell outputs:
+```
+make notebooks
+```
+
+> **NOTE** - The example notebooks run task graphs on TileDB Cloud, which requires a TileDB Cloud account and a valid API key.
+
+
+## Render Documentation
+Run the following command from the root of the repository to render the documentation:
+
+```
+make docs
+```

documentation/requirements-doc.txt

@@ -0,0 +1,9 @@
+# requirements to execute example notebooks
+tiledb
+tiledb.cloud
+jupyterlab
+seaborn
+plotly
+networkx
+pydot
+ipywidgets