Globus slurm transfer script

.github/workflows/README.md

@@ -0,0 +1,185 @@
+# GitHub Actions Documentation Deployment Workflow
+
+## Overview
+
+The `.github/workflows/docs.yml` workflow automatically builds and deploys MkDocs Material documentation to GitHub Pages when changes are merged into the `main` branch.
+
+## Trigger Conditions
+
+The workflow runs when:
+
+1. **Manual trigger**: Via the Actions tab (`workflow_dispatch`)
+2. **Automatic trigger**: Push to `main` branch when any of these paths change:
+   - `docs/**` - Documentation files
+   - `bin/**` - Source code with docstrings (e.g., `slurm_transfer.py`)
+   - `src/**` - Additional source code
+   - `mkdocs.yml` - MkDocs configuration file
+
+## What the Workflow Does
+
+### Step 1: Checkout Repository
+```yaml
+uses: actions/checkout@v4
+with:
+  fetch-depth: 0
+```
+- Checks out the repository with full history
+- `fetch-depth: 0` ensures all git history is available (required for git revision date plugin)
+
+### Step 2: Set Up Python
+```yaml
+uses: actions/setup-python@v5
+with:
+  python-version: '3.11'
+  cache: 'pip'
+```
+- Installs Python 3.11
+- Enables pip caching for faster builds
+
+### Step 3: Install Dependencies
+```bash
+pip install --upgrade pip
+pip install -r docs/requirements.txt
+```
+- Installs all required packages including:
+  - mkdocs-material
+  - mkdocstrings
+  - mkdocstrings-python
+  - All other documentation dependencies
+
+### Step 4: Configure Git
+```bash
+git config user.name github-actions[bot]
+git config user.email github-actions[bot]@users.noreply.github.com
+```
+- Configures Git for the gh-deploy command
+- Uses GitHub Actions bot identity
+
+### Step 5: Deploy Documentation
+```bash
+mkdocs gh-deploy --force --clean --verbose
+```
+- Builds the documentation
+- Deploys to the `gh-pages` branch
+- `--force`: Overwrites existing deployment
+- `--clean`: Removes old files not in current build
+- `--verbose`: Detailed output for debugging
+
+## Permissions
+
+```yaml
+permissions:
+  contents: write
+```
+
+The workflow has `contents: write` permission, which allows it to:
+- Push to the `gh-pages` branch
+- Update GitHub Pages deployment
+
+## GitHub Pages Setup
+
+To enable the documentation site:
+
+1. Go to repository **Settings** → **Pages**
+2. Under "Build and deployment":
+   - **Source**: Deploy from a branch
+   - **Branch**: `gh-pages` / `(root)`
+3. Click **Save**
+
+The site will be available at: `https://openomics.github.io/arc/`
+
+## Viewing Deployment Status
+
+Monitor deployment in several places:
+
+### 1. Actions Tab
+- View workflow runs: `https://github.com/OpenOmics/arc/actions`
+- See build logs and any errors
+- Check deployment status
+
+### 2. Commits
+- Successful deployments show a ✓ next to the commit
+- Click the checkmark to see workflow details
+
+### 3. Environments
+- Go to repository main page
+- Look for "Environments" in the right sidebar
+- Shows active deployments and URLs
+
+## Testing Locally
+
+Before pushing changes, test documentation locally:
+
+```bash
+# Install dependencies
+pip install -r docs/requirements.txt
+
+# Serve locally with live reload
+mkdocs serve
+
+# Build to verify no errors
+mkdocs build --strict
+```
+
+Access local docs at: http://127.0.0.1:8000
+
+## Troubleshooting
+
+### Build Fails on Missing Dependencies
+
+**Problem**: Workflow fails with "ModuleNotFoundError"
+
+**Solution**: Ensure all required packages are in `docs/requirements.txt`
+
+### Documentation Not Updating
+
+**Problem**: Changes pushed but site doesn't update
+
+**Check**:
+1. Did changes affect monitored paths?
+2. Was push to `main` branch?
+3. Check Actions tab for errors
+4. Verify GitHub Pages is enabled
+
+### mkdocstrings Import Errors
+
+**Problem**: Cannot import modules for docstring extraction
+
+**Solution**: Ensure `bin/__init__.py` exists and modules are importable
+
+### Permission Denied
+
+**Problem**: Workflow fails with permission errors
+
+**Solution**: 
+1. Verify `permissions: contents: write` is set
+2. Check repository Settings → Actions → General → Workflow permissions
+3. Ensure "Read and write permissions" is selected
+
+## Manual Deployment
+
+To manually trigger deployment:
+
+1. Go to **Actions** tab
+2. Select **docs** workflow
+3. Click **Run workflow**
+4. Select `main` branch
+5. Click **Run workflow**
+
+## Workflow Updates
+
+When updating the workflow:
+
+1. Edit `.github/workflows/docs.yml`
+2. Test changes on a feature branch first
+3. Merge to main to activate new workflow
+
+## Auto-Documentation Feature
+
+The workflow automatically extracts and renders:
+- Function docstrings from `bin/slurm_transfer.py`
+- Any other Python modules in `bin/` and `src/`
+- Google-style docstrings → formatted HTML
+- Type hints → displayed in signatures
+
+Changes to Python source code docstrings will automatically update the documentation when merged to main!

.github/workflows/docs.yml

@@ -1,18 +1,43 @@
 name: docs
+
 on:
   workflow_dispatch:
   push:
+    branches:
+      - main
     paths:
       - 'docs/**'
+      - 'bin/**'
+      - 'src/**'
+      - 'mkdocs.yml'
+
+permissions:
+  contents: write
 
 jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
         with:
-          python-version: 3.9
-      - run: pip install --upgrade pip
-      - run: pip install -r docs/requirements.txt
-      - run: mkdocs gh-deploy --force
+          python-version: '3.11'
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: |
+          pip install --upgrade pip
+          pip install -r docs/requirements.txt
+
+      - name: Configure Git
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email github-actions[bot]@users.noreply.github.com
+
+      - name: Deploy documentation
+        run: mkdocs gh-deploy --force --clean --verbose

bin/__init__.py

@@ -0,0 +1 @@
+"""Bin module containing utility scripts for arc."""