documentation site prototype

Author: zachary-foster

.github/workflows/docs.yml

@@ -0,0 +1,67 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+          pip install quartodoc
+
+      - name: Setup Quarto
+        uses: quarto-dev/quarto-actions/setup@v2
+
+      - name: Build API documentation
+        run: |
+          cd docs
+          quartodoc build
+
+      - name: Render Quarto site
+        run: |
+          cd docs
+          quarto render
+
+      - name: Upload artifact
+        if: github.event_name != 'pull_request'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_site
+
+  deploy:
+    if: github.event_name != 'pull_request'
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -50,6 +50,10 @@ venv.bak/
 
 # Documentation build output
 /site
+docs/_site/
+docs/reference/
+!docs/reference/.gitkeep
+!docs/reference/index.qmd
 
 # Hatch
 .hatch/
@@ -63,3 +67,5 @@ Desktop.ini
 # Local development
 *.local
 local/
+
+.ipynb_checkpoints

AGENTS.md

@@ -35,6 +35,19 @@ hatch run fix
    - functions/vars: `snake_case`
    - constants: `UPPER_SNAKE_CASE`
 
+## Coding conventions
+
+- Complexity is a liability and should only be introduced when it has significant benefits.
+- Dont write short wrapper functions for other functions.
+- Only check types and parameter validity on public APIs.
+
+
+## Testing conventions
+
+- Dont write trivial tests; no tests for the sake of tests.
+- Only test public APIs.
+- Dont design tests to pass, design tests that test what the user expects to happen or fail.
+- This pacakge primarily embeds JS widgets. The effect they have on the dom should be tested with playwright
 
 ## Before Submitting Changes
 

README.md

@@ -16,6 +16,11 @@ package.
 pip install heattree_py
 ```
 
+## Documentation
+
+Full documentation with interactive examples is available at:
+**https://grunwaldlab.github.io/heattree_py/**
+
 ## Quick start
 
 ```python

docs/.gitignore

@@ -0,0 +1,2 @@
+/.quarto/
+**/*.quarto_ipynb

docs/_quarto.yml

@@ -0,0 +1,56 @@
+project:
+  type: website
+  output-dir: _site
+
+website:
+  title: "heattree_py"
+  description: "Interactive phylogenetic tree visualization for Jupyter notebooks"
+  navbar:
+    left:
+      - href: index.qmd
+        text: Home
+      - getting-started.qmd
+      - examples.qmd
+      - href: reference/index.qmd
+        text: API Reference
+    right:
+      - icon: github
+        href: https://github.com/grunwaldlab/heattree_py
+  sidebar:
+    - title: Getting Started
+      contents:
+        - getting-started.qmd
+    - title: Examples
+      contents:
+        - examples.qmd
+    - title: API Reference
+      contents:
+        - section: Core Functions
+          contents:
+            - reference/heat_tree.qmd
+            - reference/example_data.qmd
+            - reference/HeatTreeWidget.qmd
+
+# quartodoc configuration for API reference
+quartodoc:
+  style: pkgdown
+  dir: reference
+  package: heattree_py
+  title: API Reference
+  sidebar: reference/_sidebar.yml
+  parser: google
+  sections:
+    - title: Core Functions
+      desc: Main visualization functions
+      contents:
+        - heat_tree
+        - example_data
+        - HeatTreeWidget
+
+format:
+  html:
+    theme: cosmo
+    css: styles.css
+    toc: true
+    code-copy: true
+    code-overflow: wrap

docs/examples.qmd

@@ -0,0 +1,57 @@
+---
+title: "Examples"
+---
+
+This page showcases real-world examples using published phylogenetic datasets.
+
+## Weisberg et al. 2020
+
+Phylogenetic trees of *Agrobacterium* isolates from a study on virulence plasmid conservation and transmission:
+
+> Alexandra J. Weisberg et al., Unexpected conservation and global transmission
+> of agrobacterial virulence plasmids. Science 368, eaba5256 (2020).
+
+The widget below contains both the MLSA (multilocus sequence analysis) tree and
+the time-calibrated BEAST tree. Use the "Select tree" dropdown in the toolbar's
+"Data" tab to switch between them.
+
+```{python}
+from heattree_py import heat_tree, example_data
+
+heat_tree(
+    tree=[
+        example_data("weisberg_2020_mlsa"),
+        example_data("weisberg_2020_beast")
+    ],
+    metadata=[
+        example_data("weisberg_2020_metadata"),
+        example_data("weisberg_2020_metadata")
+    ],
+    aesthetics=[
+        {"tipLabelText": "strain", "tipLabelColor": "host_type"},
+        {"tipLabelText": "strain", "tipLabelColor": "year_isolated"}
+    ],
+    tree_names=["MLSA", "BEAST"],
+    layout="circular"
+)
+```
+
+## Bansal et al. 2021
+
+Phylogenetic tree from a comparative genomics study of *Xylella*:
+
+> Bansal, K., Kumar, S., Kaur, A., Singh, A., & Patil, P. B. (2021). Deep
+> phylo-taxono genomics reveals Xylella as a variant lineage of plant associated
+> Xanthomonas and supports their taxonomic reunification along with
+> Stenotrophomonas and Pseudoxanthomonas. Genomics, 113(6), 3989-4003.
+
+```{python}
+heat_tree(
+    example_data("bansal_2021_tree"),
+    metadata=example_data("bansal_2021_metadata"),
+    aesthetics={
+        "tipLabelText": "Strain",
+        "tipLabelColor": "Lifestyle"
+    }
+)
+```