Skip to content

Commit d7cb48c

Browse files
committed
pulling in a lua script to handle path rejiggering because pandoc contains a lua interpreter
1 parent 90ff5c3 commit d7cb48c

File tree

10 files changed

+1035
-18
lines changed

10 files changed

+1035
-18
lines changed

.gitignore

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,8 @@
7070
!/docs/*.qmd
7171
!/docs/*.md
7272
!/docs/*.css
73+
!/docs/*.lua
74+
!/docs/*.py
7375

7476
# globus adapter
7577
!/globus

CLAUDE.md

Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,15 +52,23 @@ uv run pytest bin/test_*.py
5252
# Or run tests with tox for multiple environments
5353
tox
5454

55-
# Build documentation
55+
# Build documentation website in _site/
5656
just docs
5757

58+
# Preview documentation website locally
59+
just preview-site
60+
5861
# IMPORTANT: Modifying README.md
5962
# The README.md in the project root is generated from docs/index.qmd
6063
# NEVER edit README.md directly - it will be overwritten
6164
# Always edit docs/index.qmd and re-render:
6265
just make-readme # or: just docs
6366

67+
# IMPORTANT: Documentation Website Structure
68+
# This is a monorepo where docs/ contains Quarto source files for the documentation website
69+
# The website is built to _site/ and deployed to GitHub Pages
70+
# Post-render scripts in docs/ fix paths for proper website navigation
71+
6472
# Docker operations
6573
just docker-build
6674
just docker-push
@@ -69,13 +77,25 @@ just docker-push
6977
## Architecture
7078

7179
### Directory Structure
80+
81+
This is a **monorepo** that contains both the Nextflow bioinformatics pipeline and its documentation website source:
82+
83+
#### Pipeline Components
7284
- `main.nf` - Main workflow entry point that orchestrates platform-specific workflows
7385
- `workflows/` - Platform-specific workflows (nanopore.nf, illumina.nf)
7486
- `subworkflows/` - Reusable workflow components (alignment, variant_calling, primer_handling, etc.)
7587
- `modules/` - Individual process definitions for tools (dorado, minimap2, ivar, etc.)
7688
- `bin/` - Python utility scripts with PEP 723 inline dependencies (fully portable with uv)
7789
- `conf/` - Configuration files for different platforms and tools
7890

91+
#### Documentation Website
92+
- `docs/` - Quarto source files for the documentation website
93+
- `*.qmd` files - Quarto markdown source files
94+
- `fix-index-paths.lua` - Post-render script for fixing paths in generated HTML
95+
- `fix-index-paths.py` - Python alternative to the Lua script
96+
- `_quarto.yml` - Quarto configuration for building the documentation website
97+
- `_site/` - Generated static website output (git-ignored)
98+
7999
### Key Workflow Components
80100

81101
1. **Data Ingestion** - Handles multiple input formats (pod5, BAM, FASTQ) with optional remote file watching

_quarto.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ project:
44
render:
55
- "docs/*.qmd"
66
post-render:
7-
- "just fix-index-paths"
7+
- docs/fix-index-paths.lua
88

99
website:
1010
title: "OneRoof Documentation"

docs/fix-index-paths.lua

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
#!/usr/bin/env lua
2+
3+
-- fix-index-paths.lua
4+
-- Post-render script to fix paths in the generated site
5+
-- This script:
6+
-- 1. Copies docs/index.html to the site root and fixes relative paths
7+
-- 2. Copies markdown files from _site/docs back to docs directory
8+
9+
-- Helper function to check if file exists
10+
local function file_exists(path)
11+
local f = io.open(path, "r")
12+
if f ~= nil then
13+
io.close(f)
14+
return true
15+
else
16+
return false
17+
end
18+
end
19+
20+
-- Helper function to check if directory exists
21+
local function dir_exists(path)
22+
-- Try to open the directory as a file, which will fail
23+
-- Then try using a platform-agnostic approach
24+
local f = io.open(path .. "/.", "r")
25+
if f then
26+
io.close(f)
27+
return true
28+
end
29+
return false
30+
end
31+
32+
-- Helper function to read file
33+
local function read_file(path)
34+
local f = io.open(path, "r")
35+
if not f then
36+
return nil
37+
end
38+
local content = f:read("*all")
39+
f:close()
40+
return content
41+
end
42+
43+
-- Helper function to write file
44+
local function write_file(path, content)
45+
local f = io.open(path, "w")
46+
if not f then
47+
return false
48+
end
49+
f:write(content)
50+
f:close()
51+
return true
52+
end
53+
54+
-- Helper function to copy file
55+
local function copy_file(src, dest)
56+
local content = read_file(src)
57+
if content then
58+
return write_file(dest, content)
59+
end
60+
return false
61+
end
62+
63+
-- Helper function to list files in directory
64+
local function list_files(dir, pattern)
65+
local files = {}
66+
local command
67+
68+
-- Detect OS and use appropriate command
69+
if package.config:sub(1, 1) == "\\" then
70+
-- Windows
71+
command = 'dir /b "' .. dir .. '" 2>nul'
72+
else
73+
-- Unix-like (Linux, macOS)
74+
command = 'ls "' .. dir .. '" 2>/dev/null'
75+
end
76+
77+
local handle = io.popen(command)
78+
if handle then
79+
for file in handle:lines() do
80+
if pattern and file:match(pattern) then
81+
table.insert(files, file)
82+
elseif not pattern then
83+
table.insert(files, file)
84+
end
85+
end
86+
handle:close()
87+
end
88+
89+
return files
90+
end
91+
92+
-- Main function
93+
local function main()
94+
-- Define paths relative to project root
95+
local site_dir = "_site"
96+
local docs_dir = "docs"
97+
local source_index = site_dir .. "/docs/index.html"
98+
local dest_index = site_dir .. "/index.html"
99+
100+
-- Part 1: Copy and fix index.html
101+
if file_exists(source_index) then
102+
local content = read_file(source_index)
103+
if content then
104+
-- Fix relative paths
105+
content = content:gsub('href="../docs/', 'href="docs/')
106+
content = content:gsub('src="../site_libs/', 'src="site_libs/')
107+
108+
if write_file(dest_index, content) then
109+
print("✓ Fixed paths in root index.html")
110+
else
111+
print("⚠️ Failed to write fixed index.html")
112+
end
113+
else
114+
print("⚠️ Failed to read " .. source_index)
115+
end
116+
else
117+
print("⚠️ No _site directory found - using default homepage")
118+
end
119+
120+
-- Part 2: Copy markdown files back to docs directory
121+
local site_docs_dir = site_dir .. "/docs"
122+
if dir_exists(site_docs_dir) then
123+
local md_files = list_files(site_docs_dir, "%.md$")
124+
local copied = false
125+
126+
for _, file in ipairs(md_files) do
127+
local src = site_docs_dir .. "/" .. file
128+
local dest = docs_dir .. "/" .. file
129+
if copy_file(src, dest) then
130+
copied = true
131+
end
132+
end
133+
134+
if copied then
135+
print("✓ Markdown files copied to docs/")
136+
else
137+
print("⚠️ No markdown files found")
138+
end
139+
end
140+
end
141+
142+
-- Run the script
143+
main()

docs/fix-index-paths.py

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
#!/usr/bin/env python3
2+
# /// script
3+
# requires-python = ">=3.10"
4+
# ///
5+
6+
"""
7+
fix-index-paths.py
8+
Post-render script to fix paths in the generated site
9+
This script:
10+
1. Copies docs/index.html to the site root and fixes relative paths
11+
2. Copies markdown files from _site/docs back to docs directory
12+
"""
13+
14+
import re
15+
import shutil
16+
from pathlib import Path
17+
18+
19+
def main():
20+
# Define paths relative to project root
21+
site_dir = Path("_site")
22+
docs_dir = Path("docs")
23+
source_index = site_dir / "docs" / "index.html"
24+
dest_index = site_dir / "index.html"
25+
26+
# Part 1: Copy and fix index.html
27+
if source_index.exists():
28+
try:
29+
# Read the content
30+
content = source_index.read_text(encoding="utf-8")
31+
32+
# Fix relative paths
33+
content = re.sub(r'href="../docs/', 'href="docs/', content)
34+
content = re.sub(r'src="../site_libs/', 'src="site_libs/', content)
35+
36+
# Write the fixed content
37+
dest_index.write_text(content, encoding="utf-8")
38+
print("✓ Fixed paths in root index.html")
39+
40+
except Exception as e:
41+
print(f"⚠️ Failed to process index.html: {e}")
42+
else:
43+
print("⚠️ No _site directory found - using default homepage")
44+
45+
# Part 2: Copy markdown files back to docs directory
46+
site_docs_dir = site_dir / "docs"
47+
if site_docs_dir.is_dir():
48+
copied = False
49+
try:
50+
for md_file in site_docs_dir.glob("*.md"):
51+
dest_file = docs_dir / md_file.name
52+
shutil.copy2(md_file, dest_file)
53+
copied = True
54+
55+
if copied:
56+
print("✓ Markdown files copied to docs/")
57+
else:
58+
print("⚠️ No markdown files found")
59+
60+
except Exception as e:
61+
print(f"⚠️ Failed to copy markdown files: {e}")
62+
63+
64+
if __name__ == "__main__":
65+
main()

docs/whats-that-file.qmd

Lines changed: 30 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -619,14 +619,43 @@ Project documentation sources:
619619
- Storage and organization practices
620620
- Best practices documentation
621621

622+
**whats-that-file.qmd** & **whats-that-file.md**
623+
624+
- This file - comprehensive file reference
625+
- Documents every file in the repository
626+
- Helps developers understand project structure
627+
628+
### Post-Render Scripts
629+
630+
**fix-index-paths.lua**
631+
632+
- Lua script for Quarto post-render processing
633+
- Fixes relative paths in generated HTML
634+
- Copies markdown files back to docs directory
635+
- Ensures proper website navigation structure
636+
637+
**fix-index-paths.py**
638+
639+
- Python alternative to the Lua script
640+
- Same functionality as fix-index-paths.lua
641+
- Provides fallback option if Lua is unavailable
642+
- Uses standard library for cross-platform compatibility
643+
622644
### Generated Files
623645

624-
**pipeline_architecture_files/**
646+
**site_libs/**
625647

626648
- Quarto-generated web assets
627649
- JavaScript, CSS, and fonts
650+
- Bootstrap and Quarto theme files
628651
- Supports interactive documentation
629652

653+
**_site/**
654+
655+
- Rendered documentation website
656+
- HTML output from Quarto
657+
- Ready for deployment to GitHub Pages
658+
630659
## globus/ Directory
631660

632661
Globus integration for data transfer:

justfile

Lines changed: 1 addition & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -79,17 +79,7 @@ copy-index:
7979
[group('docs')]
8080
[private]
8181
fix-index-paths:
82-
@if [ -f "_site/docs/index.html" ]; then \
83-
cp _site/docs/index.html _site/index.html && \
84-
sed -i.bak 's|href="../docs/|href="docs/|g' _site/index.html && \
85-
sed -i.bak 's|src="../site_libs/|src="site_libs/|g' _site/index.html && \
86-
rm -f _site/index.html.bak && \
87-
echo "✓ Fixed paths in root index.html"; \
88-
fi
89-
@# Copy markdown back to docs directory
90-
@if [ -d "_site/docs" ]; then \
91-
cp _site/docs/*.md docs/ 2>/dev/null && echo "✓ Markdown files copied to docs/" || echo "⚠️ No markdown files found"; \
92-
fi
82+
@lua docs/fix-index-paths.lua
9383

9484
# Set up the Python environment with Pixi.
9585
[group('setup')]

llms.txt

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,11 +12,14 @@
1212

1313
## Project Structure
1414

15+
This is a **monorepo** containing both the Nextflow bioinformatics pipeline and its documentation website source.
16+
1517
### Core Files
1618
- `main.nf` - Main Nextflow workflow entry point
1719
- `nextflow.config` - Pipeline configuration
1820
- `pyproject.toml` - Python dependencies and project metadata
1921
- `justfile` - Common development commands
22+
- `_quarto.yml` - Quarto configuration for documentation website
2023

2124
### Workflows
2225
- `workflows/nanopore.nf` - Nanopore data processing workflow
@@ -29,9 +32,13 @@
2932
- `lib/Utils.groovy` - Shared Groovy utilities
3033

3134
### Documentation
32-
- `README.md` - Main documentation and usage guide
35+
- `README.md` - Main documentation (generated from docs/index.qmd - DO NOT EDIT DIRECTLY)
3336
- `CLAUDE.md` - Guidelines for AI assistants working with this codebase
34-
- `docs/` - Additional documentation (architecture, development, data management)
37+
- `docs/` - Quarto source files for documentation website
38+
- `*.qmd` files - Quarto markdown sources
39+
- `fix-index-paths.lua` - Post-render script for fixing HTML paths
40+
- `fix-index-paths.py` - Python alternative post-render script
41+
- `_site/` - Generated documentation website output (git-ignored)
3542
- `tests/README.md` - Test suite documentation
3643

3744
### Configuration
@@ -89,7 +96,9 @@ just test-pipeline # Test end-to-end functionality
8996

9097
### Common Commands
9198
```bash
92-
just docs # Build documentation (including README)
99+
just docs # Build documentation website and README
100+
just preview-site # Preview documentation website locally
101+
just make-readme # Generate README.md from docs/index.qmd
93102
just docker-build # Build Docker image
94103
ruff check . --fix # Lint Python code
95104
ruff format . # Format Python code

0 commit comments

Comments
 (0)