Merge branch 'dev'

Author: nrminor

.github/workflows/docs.yml

@@ -0,0 +1,42 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pages: write
+  id-token: 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
+        with:
+          version: latest
+
+      - name: Render documentation
+        run: |
+          quarto render
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./_site
+          publish_branch: gh-pages
+          force_orphan: true
+          user_name: 'github-actions[bot]'
+          user_email: 'github-actions[bot]@users.noreply.github.com'
+          commit_message: 'Deploy documentation for ${{ github.sha }}'

.gitignore

@@ -71,6 +71,7 @@
 !/docs/*.md
 !/docs/*.pdf
 !/docs/*.html.gz
+!/docs/*.css
 
 # globus adapter
 !/globus
@@ -94,3 +95,5 @@
 !tests/**/*.nf.test
 !tests/data/
 !tests/data/**/*
+
+/.quarto/

_quarto.yml

@@ -1,10 +1,96 @@
 project:
-  output-dir: docs
-  post-render: just readme
+  type: website
+  output-dir: _site
+  render:
+    - "docs/*.qmd"
+  post-render:
+    - "just copy-index"
 
-toc: true
-number-sections: true
-# bibliography: references.bib 
+website:
+  title: "OneRoof Documentation"
+  description: "Comprehensive documentation for the OneRoof bioinformatics pipeline"
+  site-url: https://nrminor.github.io/oneroof/
+  repo-url: https://github.com/nrminor/oneroof
+
+  navbar:
+    background: primary
+    left:
+      - href: docs/index.qmd
+        text: "Home"
+      - href: docs/developer.qmd
+        text: "Developer Guide"
+      - href: docs/pipeline_architecture.qmd
+        text: "Architecture"
+      - href: docs/whats-that-file.qmd
+        text: "File Reference"
+      - href: docs/data_management.qmd
+        text: "Data Management"
+    # right:
+    #   - icon: github
+    #     href: https://github.com/nrminor/oneroof
+    #   - icon: docker
+    #     href: https://hub.docker.com/r/nrminor/dorado-and-friends
+    tools:
+      - icon: github
+        menu:
+          - text: Source Code
+            href: https://github.com/nrminor/oneroof
+          - text: Report Issue
+            href: https://github.com/nrminor/oneroof/issues
+    collapse: true
+    collapse-below: lg
+    toggle-position: right
+
+  sidebar:
+    style: "docked"
+    search: true
+  #   contents:
+  #     - section: "Getting Started"
+  #       contents:
+  #         - docs/index.qmd
+  #         - text: "Installation"
+  #           href: docs/index.qmd#installation
+  #         - text: "Quick Start"
+  #           href: docs/index.qmd#quick-start
+  #     - section: "Development"
+  #       contents:
+  #         - docs/developer.qmd
+  #         - docs/pipeline_architecture.qmd
+  #     - section: "Reference"
+  #       contents:
+  #         - docs/whats-that-file.qmd
+  #         - docs/data_management.qmd
+
+  back-to-top-navigation: true
+  page-navigation: true
+  reader-mode: true
+
+  page-footer:
+    left: |
+      © 2025 OneRoof Contributors
+    center: |
+      [MIT License](https://github.com/nrminor/oneroof/blob/main/LICENSE)
+    right: |
+      Built with [Quarto](https://quarto.org/)
+
+format:
+  html:
+    theme:
+      light: flatly
+      dark: darkly
+    css: docs/styles.css
+    toc: true
+    toc-depth: 3
+    toc-location: right
+    code-fold: false
+    code-tools: true
+    code-copy: true
+    code-overflow: wrap
+    highlight-style: github
+    link-external-icon: false
+    link-external-newwindow: true
+    smooth-scroll: true
+    anchor-sections: true
 
 execute:
   freeze: auto

docs/.gitignore

@@ -0,0 +1 @@
+/.quarto/

docs/data_management.pdf

@@ -11,9 +11,11 @@
 
 Most `oneroof` development happens in the `dev` branch of this repo. To get started with doing so yourself, clone and switch to the `dev` branch like so:
 
-    git clone https://github.com/nrminor/oneroof.git && \
-    cd oneroof && \
-    git checkout dev
+``` bash
+git clone https://github.com/nrminor/oneroof.git && \
+cd oneroof && \
+git checkout dev
+```
 
 From there, you’ll have a few tools to consider installing if you haven’t already:
 
@@ -97,7 +99,7 @@ Like most Nextflow pipelines, `oneroof` also has a few other important directori
 
 We’re big fans of the [Ruff](https://docs.astral.sh/ruff/) linter and formatter, and we use it liberally in the writing of our Python scripts. To do so yourself in VSCode, we offer the following configuration for your User Settings JSON:
 
-``` json
+``` jsonc
 {
   "[python]": {
     "editor.defaultFormatter": "charliermarsh.ruff",

docs/developer.md

@@ -16,7 +16,7 @@ engine: knitr
 
 Most `oneroof` development happens in the `dev` branch of this repo. To get started with doing so yourself, clone and switch to the `dev` branch like so:
 
-```
+```bash
 git clone https://github.com/nrminor/oneroof.git && \
 cd oneroof && \
 git checkout dev
@@ -104,7 +104,7 @@ Like most Nextflow pipelines, `oneroof` also has a few other important directori
 
 We're big fans of the [Ruff](https://docs.astral.sh/ruff/) linter and formatter, and we use it liberally in the writing of our Python scripts. To do so yourself in VSCode, we offer the following configuration for your User Settings JSON:
 
-```json
+```jsonc
 {
   "[python]": {
     "editor.defaultFormatter": "charliermarsh.ruff",

docs/developer.pdf

@@ -1,5 +1,5 @@
 ---
-title: "OneRoof: A Pipeline Prototype for Base-, Variant-, and Consensus-calling under One Proverbial Roof"
+title: "OneRoof: Base-, Variant-, and Consensus-calling under One Proverbial Roof."
 toc: true
 format:
     html:
@@ -19,7 +19,7 @@ execute:
 
 ## Overview
 
-`oneroof` is a pipeline designed to take a common series of bioinformatic tasks (see below) and put them under "one roof". We mean this quite literally: the pipeline will perform at its best when run on networked devices in the same building.
+`oneroof` is a [Nextflow](https://nextflow.io/) pipeline designed to take a common series of bioinformatic tasks (see below) and put them under "one roof". We mean this literally as well as figuratively: the pipeline will perform certain tasks best when run on networked devices in the same building.
 
 `oneroof` was originally developed in the early stages of the [United States Bovine Highly Pathogenic Avian Influenza (HPAI) outbreak of 2024](https://nextstrain.org/avian-flu/h5n1/ha/2y), when we wanted one, configurable, easy-to-run pipeline that would do all of the following seamlessly:
 
@@ -79,7 +79,7 @@ Command line argument     | Default value | Explanation
 `--primer_bed`            | None          | A bed file of primer coordinates relative to the reference provided with the parameters `refseq` and `ref_gbk`.
 `--refseq`                | None          | The reference sequence to be used for mapping in FASTA format.
 `--ref_gbk`               | None          | The reference sequence to be used for variant annotation in Genbank format.
-`--remote_pod5_location`  | None          | A remote location to use with a TCP stream to watch for pod5 files in realtime as they are generated by the sequencing instrument.
+`--remote_pod5_location`  | None          | A remote location to use with an SSH client to watch for pod5 files in realtime as they are generated by the sequencing instrument.
 `--file_watcher_config`   | None          | Configuration file for remote file monitoring. An example can be found at conf/file_watcher.template.yml.
 `--pod5_dir`              | None          | If a remote pod5 location isn't given, users may provide a local, on-device directory where pod5 files have been manually transferred.
 `--precalled_staging`     | None          | A local directory to watch for Nanopore FASTQs or BAMs as the become available. This is for cases where basecalling is being performed via another workflow, resulting in BAMs or FASTQs that are gradually transferred into  `params.precalled_staging` as basecalling completes.
@@ -146,7 +146,7 @@ nextflow run . \
 
 Especially on Apple Silicon Macs, this will reduce the overhead of using the Docker Virtual Machine and allow the pipeline to invoke tools installed directly within the local project environment.
 
-Note also that more information on the repo's files is available in our [developer guide](docs/developer.md).
+Note also that more information on the repo's files is available in our [developer guide](developer.qmd).
 
 ## Testing
 
@@ -188,21 +188,21 @@ Tests are organized in the `tests/` directory:
 
 The test suite uses minimal synthetic data to ensure fast execution while still exercising all key pipeline features. Tests are automatically run in CI/CD on all pull requests and pushes to main branches.
 
-For more details on the testing framework and how to write new tests, see the [test suite documentation](tests/README.md).
+For more details on the testing framework and how to write new tests, see the [test suite documentation](../tests/README.md).
 
 ## Further Documentation
 
 For more detailed information about specific aspects of the OneRoof pipeline, please refer to the following documentation:
 
-- **[Developer Guide](docs/developer.md)** - Comprehensive guide for developers working with the codebase, including project structure, coding standards, and development workflows
-- **[Pipeline Architecture](docs/pipeline_architecture.md)** - Detailed technical documentation of the pipeline's architecture, including workflow diagrams, module descriptions, and data flow
-- **[File Reference Guide](docs/whats-that-file.md)** - Complete listing of all files in the repository with descriptions of their purpose and functionality
-- **[Globus Integration](globus/README.md)** - Instructions for setting up and using Globus integration for automated data transfer and remote workflow execution
-- **[Test Suite Documentation](tests/README.md)** - Guide to the testing framework, including how to write and run tests, test data organization, and CI/CD integration
+- **[Developer Guide](developer.qmd)** - Comprehensive guide for developers working with the codebase, including project structure, coding standards, and development workflows
+- **[Pipeline Architecture](pipeline_architecture.qmd)** - Detailed technical documentation of the pipeline's architecture, including workflow diagrams, module descriptions, and data flow
+- **[File Reference Guide](whats-that-file.qmd)** - Complete listing of all files in the repository with descriptions of their purpose and functionality
+- **[Globus Integration](../globus/README.md)** - Instructions for setting up and using Globus integration for automated data transfer and remote workflow execution
+- **[Test Suite Documentation](../tests/README.md)** - Guide to the testing framework, including how to write and run tests, test data organization, and CI/CD integration
 
 ## Contributing
 
-Contributions, feature requests, improvement suggestions, and bug reports via GitHub issues are all welcome! For more information on how to work with the project and what all the repo files are, see our [developer guide](docs/developer.md).
+Contributions, feature requests, improvement suggestions, and bug reports via GitHub issues are all welcome! For more information on how to work with the project and what all the repo files are, see our [developer guide](developer.qmd).
 
 ## Is it any good?