add docs

.github/actions/setup-rust/action.yml

@@ -0,0 +1,22 @@
+name: 'Setup Rust'
+description: 'Setup rust toolchain'
+inputs:
+  cache:
+    description: 'Cache'
+    required: false
+    default: false
+runs:
+  using: "composite"
+  steps: 
+    - name: Install Rust
+      uses: actions-rs/toolchain@v1
+      with:
+        profile: minimal
+        toolchain: stable
+        override: true
+
+    - name: Cache rust build
+      uses: Swatinem/rust-cache@v2
+      if: ${{ inputs.cache == 'true' }}
+      with:
+        workspaces: "precellar -> target"

.github/workflows/docs.yml

@@ -0,0 +1,103 @@
+name: build-documentation
+
+on:
+  workflow_run:
+    workflows: [test-python-package]
+    types: 
+      - completed
+
+jobs:
+  build_docs:
+    runs-on: ubuntu-latest
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
+    steps:
+    - name: Checkout code
+      uses: nschloe/action-cached-lfs-checkout@v1
+      with:
+        ref: ${{ github.event.workflow_run.head_sha }}
+
+    - uses: actions/setup-python@v5
+      name: Install Python
+      with:
+          python-version: '3.10'
+
+    - name: Install dependency
+      run: |
+        sudo apt-get install -y pandoc jq
+        sudo pip install --upgrade pip
+        pip install --user sphinx==7.* pydata-sphinx-theme==0.15.* pandoc nbsphinx \
+          Pygments==2.16.* sphinx-autodoc-typehints myst-parser \
+          markupsafe==2.1.* sphinx-plotly-directive
+
+    - name: Download wheel files from artifacts
+      id: download-artifact
+      uses: dawidd6/action-download-artifact@v2
+      with:
+        workflow: test_python.yml
+        commit: ${{ github.event.workflow_run.head_sha }}
+        name: wheel-files
+        path: wheel_files
+
+    - name: Install wheel files
+      run: pip install --user wheel_files/*.whl
+
+    - name: Build doc
+      run: sphinx-build ${GITHUB_WORKSPACE}/docs _build/html
+
+    - name: Get SnapATAC2 version
+      id: get_version
+      run: |
+        VERSION_NUMBER=$(python -c "import precellar;print('.'.join(precellar.__version__.split('.')[:2]))")
+        echo $VERSION_NUMBER
+        echo "VERSION=$VERSION_NUMBER" >> $GITHUB_ENV
+        IS_DEV=$(python -c "import precellar;print('dev' in precellar.__version__)")
+        echo $IS_DEV
+        BRANCH_NAME=${{ github.event.workflow_run.head_branch }}
+        if [[ $IS_DEV == "True" && $BRANCH_NAME == "main" ]]; then
+          echo "DEPLOY_DEV=true" >> $GITHUB_ENV
+        elif [[ $BRANCH_NAME =~ ^v[0-9]+ || $BRANCH_NAME == "main" ]]; then
+          echo "DEPLOY_VERSION=true" >> $GITHUB_ENV
+        fi
+
+    - name: Deploy 🚀
+      uses: JamesIves/github-pages-deploy-action@v4
+      if: ${{ env.DEPLOY_DEV == 'true' }}
+      with:
+        single-commit: true
+        branch: gh-pages
+        folder: _build/html
+        clean: true
+        target-folder: /version/dev/
+
+    - name: Deploy (version) 🚀
+      uses: JamesIves/github-pages-deploy-action@v4
+      if: ${{ env.DEPLOY_VERSION == 'true' }}
+      with:
+        single-commit: true
+        branch: gh-pages
+        folder: _build/html
+        clean: true
+        target-folder: /version/${{ env.VERSION }}/
+
+    - name: Fetch JSON and Get Preferred Version
+      run: |
+        #JSON=$(cat ${GITHUB_WORKSPACE}/docs/_static/versions.json)
+        JSON=$(curl -s "https://raw.githubusercontent.com/kaizhang/SnapATAC2/main/docs/_static/versions.json")
+        VERSION=$(echo "$JSON" | jq -r '.[] | select(.preferred == true) | .version')
+        echo "PREFERRED_VERSION=$VERSION" >> $GITHUB_ENV
+        echo "Preferred version is $VERSION"
+
+    - name: Checkout code from gh-pages branch into folder
+      uses: actions/checkout@v2
+      with:
+        ref: 'gh-pages'
+        path: 'gh-pages-folder'
+
+    - name: Deploy (preferred version)
+      uses: JamesIves/github-pages-deploy-action@v4
+      with:
+        single-commit: true
+        branch: gh-pages
+        folder: gh-pages-folder/version/${{ env.PREFERRED_VERSION }}
+        clean: true
+        clean-exclude: version

.github/workflows/test_python.yml

@@ -0,0 +1,45 @@
+name: test-python-package
+
+on: [push, pull_request]
+
+jobs:
+  build-and-test:
+    outputs:
+      VERSION: ${{ steps.get-version.outputs.VERSION }}
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout code
+      uses: nschloe/action-cached-lfs-checkout@v1
+
+    - uses: actions/setup-python@v4
+      name: Install Python
+      with:
+          python-version: '3.10'
+
+    - uses: ./.github/actions/setup-rust
+      with:
+        cache: true
+
+    - name: Install dependencies
+      run: |
+        sudo pip install --upgrade pip
+        pip install --user pytest hypothesis==6.72.4 wheel
+
+    - name: Build wheel files
+      run: |
+        cd ${GITHUB_WORKSPACE}/python
+        mkdir ${GITHUB_WORKSPACE}/wheel_files
+        pip wheel . --wheel-dir ${GITHUB_WORKSPACE}/wheel_files
+
+    - name: Get precellar version
+      id: get-version
+      run: |
+        VERSION_NUMBER=$(python -c "import precellar;print(precellar.__version__)")
+        echo $VERSION_NUMBER
+        echo "VERSION=$VERSION_NUMBER" >> $GITHUB_OUTPUT
+
+    - name: Upload wheel files as artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: wheel-files
+        path: ./wheel_files/precellar*.whl

docs/_static/css/custom.css

@@ -0,0 +1,15 @@
+:root {
+    // Sidebar styles
+    --pst-sidebar-secondary: 15rem;
+}
+
+/* Main page overview cards */
+
+.bd-page-width {
+    max-width: 98rem;
+}
+
+/* Dark theme tweaking */
+html[data-theme=dark] .sd-card img[src*='.svg'] {
+    filter: invert(0.82) brightness(0.8) contrast(1.2);
+}

docs/_static/versions.json

@@ -0,0 +1,18 @@
+[
+    {
+        "name": "dev",
+        "version": "dev",
+        "url": "https://kzhang.org/SnapATAC2/version/dev/"
+    },
+    {
+        "name": "2.7 (stable)",
+        "version": "2.7",
+        "preferred": true,
+        "url": "https://kzhang.org/SnapATAC2/version/2.7/"
+    },
+    {
+        "name": "2.6",
+        "version": "2.6",
+        "url": "https://kzhang.org/SnapATAC2/version/2.6/"
+    },
+]

docs/_templates/autosummary/class.rst

@@ -0,0 +1,31 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: Attributes
+
+   .. autosummary::
+      :toctree: .
+   {% for item in attributes %}
+      ~{{ fullname }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block methods %}
+   {% if methods %}
+   .. rubric:: Methods
+
+   .. autosummary::
+      :toctree: .
+   {% for item in methods %}
+      {%- if item != '__init__' %}
+      ~{{ fullname }}.{{ item }}
+      {%- endif -%}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

docs/_templates/layout.html

@@ -0,0 +1,14 @@
+{% extends "!layout.html" %}
+
+{%- block extrahead %}
+{{ super() }}
+<!-- Google tag (gtag.js) -->
+<script async src="https://www.googletagmanager.com/gtag/js?id=G-ZX9JB19KRP"></script>
+<script>
+  window.dataLayer = window.dataLayer || [];
+  function gtag(){dataLayer.push(arguments);}
+  gtag('js', new Date());
+
+  gtag('config', 'G-ZX9JB19KRP');
+</script>
+{% endblock %}

docs/api.rst

@@ -0,0 +1,17 @@
+=============
+API reference
+=============
+
+This page gives an overview of all public precellar objects, functions and
+methods.
+
+.. currentmodule:: precellar
+
+Backed AnnData objects
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. autosummary::
+    :toctree: _autosummary
+
+    align
+