Add documentation with mkdocs

.github/workflows/docs.yml

@@ -0,0 +1,29 @@
+name: docs 
+on:
+  push:
+    branches:
+      - docs 
+      - main
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material  mkdocs-include-markdown-plugin
+      - run: mkdocs gh-deploy --force

README.md

@@ -3,16 +3,21 @@
 [![Snakemake](https://img.shields.io/badge/snakemake-≥6.3.0-brightgreen.svg)](https://snakemake.github.io)
 [![GitHub actions status](https://github.com/khanlab/SPIMprep/workflows/Tests/badge.svg?branch=main)](https://github.com/khanlab/SPIMprep/actions?query=branch%3Amain+workflow%3ATests)
 
-A Snakemake workflow for pre-processing single plane illumination microscopy (SPIM, aka lightsheet microscopy)
+<!--intro-start-->
 
-Takes datasets produced by the Biotec UltraMicroscope Blaze (as a folder of tif images), and outputs a BIDS-like dataset, with a multi-channel multi-scale ome zarr file along with downsampled nifti images. 
+A Snakemake workflow for pre-processing single plane illumination microscopy (SPIM, aka lightsheet microscopy).
+
+Takes TIF images (tiled or prestitched) and outputs a validated BIDS Microscopy dataset, with a multi-channel multi-scale OME-Zarr file for each scan, along with downsampled nifti images (in a derivatives folder). 
 
 ## Requirements
 
  - Linux system with Singularity/Apptainer installed 
-   - (Note: container will be automatically pulled when you run the workflow)
+    - (Note: container will be automatically pulled when you run the workflow)
  - Python >= 3.11
- - Lightsheet data as OME tif files in a folder, or in a tar file (see tif filename pattern in `config.yml`)
+ - Lightsheet data:
+    - Raw Ultramicroscope Blaze OME TIFF files (include `blaze` in the acquisition tag)
+    - Prestitched TIFF files (include `prestitched` in the acquisition tag)
+
 
 ## Usage
 
@@ -57,7 +62,5 @@ Note: if you run the workflow on a system with large memory, you will need to se
 7. If you want to run the workflow using a batch job submission server, please see the executor plugins here: https://snakemake.github.io/snakemake-plugin-catalog/
 
 
-
-### WIP:  The usage of this workflow is described in the [Snakemake Workflow Catalog](https://snakemake.github.io/snakemake-workflow-catalog/?usage=khanlab%2Fspimprep).
-
-
+Alternate usage of this workflow (making use of conda) is described in the [Snakemake Workflow Catalog](https://snakemake.github.io/snakemake-workflow-catalog?repo=khanlab/SPIMprep).
+<!--intro-end-->

docs/index.md

@@ -0,0 +1,10 @@
+# SPIMprep
+
+
+{%
+   include-markdown "../README.md"
+   start="<!--intro-start-->"
+   end="<!--intro-end-->"
+%}
+
+

docs/workflow.md

@@ -0,0 +1,7 @@
+# Workflow
+
+## Overview
+
+
+
+

mkdocs.yml

@@ -0,0 +1,56 @@
+site_name: SPIMprep
+theme: 
+  name: material
+  features:
+    - navigation.tabs
+    - navigation.sections
+    - toc.integrate
+    - navigation.top
+    - search.suggest
+    - search.highlight
+    - content.tabs.link
+    - content.code.annotation
+    - content.code.copy
+  language: en
+  palette:
+    - scheme: default
+      toggle:
+        icon: material/toggle-switch-off-outline 
+        name: Switch to dark mode
+      primary: teal
+      accent: purple 
+    - scheme: slate 
+      toggle:
+        icon: material/toggle-switch
+        name: Switch to light mode    
+      primary: teal
+      accent: lime
+
+
+extra:
+  social:
+    - icon: fontawesome/brands/github-alt
+      link: https://github.com/khanlab/SPIMprep
+    - icon: fontawesome/brands/twitter
+      link: https://twitter.com/neuroak
+
+plugins:
+  - include-markdown
+
+markdown_extensions:
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - admonition
+  - pymdownx.arithmatex:
+      generic: true
+  - footnotes
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.mark
+  - attr_list
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:materialx.emoji.to_svg
+