docs

Torc Documentation

This directory contains the source files for Torc's user documentation, built with mdBook.

Building the Documentation

Prerequisites

Install mdBook:

cargo install mdbook

Build Commands

Build the documentation:

mdbook build

This must be run from the docs/ directory. Output will be written to docs/book/.

Serve locally with live reload:

mdbook serve

This will:

• Build the documentation
• Start a local web server at http://localhost:3000
• Watch for file changes and rebuild automatically
• Open your browser automatically

Serve on custom address:

mdbook serve --hostname 0.0.0.0 --port 8080

Clean build artifacts:

mdbook clean

Testing

Check for broken links and other issues:

mdbook test

Documentation Structure

The documentation follows the Diataxis framework:

src/
├── SUMMARY.md              # Table of contents
├── introduction.md         # Landing page
├── getting-started.md      # Quick start guide
├── installation.md         # Installation instructions
├── quick-start.md          # Basic usage
│
├── explanation/            # Understanding-oriented
│   ├── README.md
│   ├── architecture.md
│   ├── database.md
│   ├── server.md
│   ├── client.md
│   ├── job-runners.md
│   ├── job-states.md
│   ├── reinitialization.md
│   ├── dependencies.md
│
├── how-to/                 # Problem-oriented
│   ├── README.md
│   ├── creating-workflows.md
│   ├── slurm.md
│   └── resources.md
│
├── reference/              # Information-oriented
│   ├── README.md
│   ├── openapi.md
│   ├── parameterization.md
│   └── configuration.md
│
├── tutorials/              # Learning-oriented
│   ├── README.md
│   ├── many-jobs.md
│   ├── diamond.md
│   ├── user-data.md
│   ├── simple-params.md
│   └── advanced-params.md
│
└── contributing.md         # Contributing guide

Editing Documentation

1. Edit Markdown files in src/
2. If adding new pages, update src/SUMMARY.md
3. Run mdbook serve to preview changes
4. Build with mdbook build before committing

OpenAPI And Client Generation

The OpenAPI contract is emitted from Rust, not edited by hand.

From the repository root:

cd api

# Emit Rust-owned spec only
bash sync_openapi.sh emit

# Verify both checked-in spec files match Rust output
bash sync_openapi.sh check

# Promote the Rust spec into api/openapi.yaml and regenerate clients
bash sync_openapi.sh all --promote

# Regenerate Rust, Python, and Julia clients from the current checked-in spec
bash sync_openapi.sh clients

Markdown Features

mdBook supports:

• Standard Markdown - headings, lists, links, images
• Code blocks with syntax highlighting - Specify language after ```
• Tables - GitHub-flavored markdown tables
• Admonitions - Using blockquotes with specific prefixes
• Links - Relative links between pages
• Anchor links - #heading-name within pages

Example code block:

name: my_workflow
jobs:
  - name: hello
    command: echo "Hello World"

Adding New Pages

1. Create new .md file in appropriate directory
2. Add entry to SUMMARY.md:

- [New Page Title](./path/to/new-page.md)

3. Test build: mdbook build

Deployment

GitHub Pages

To deploy to GitHub Pages:

1. Build the documentation:

   mdbook build

2. The book/ directory contains the static site

3. Configure GitHub Pages to serve from docs/book/ or use GitHub Actions to build and deploy

Custom Deployment

The book/ directory is a self-contained static website. Deploy it to any web server:

# Example: Copy to web server
scp -r book/* user@server:/var/www/torc-docs/

# Example: Deploy to S3
aws s3 sync book/ s3://my-bucket/torc-docs/ --delete

Configuration

Edit book.toml to customize:

• Site title and description
• GitHub repository links
• Theme and styling
• Search settings
• Output format options

See mdBook documentation for all options.

Troubleshooting

Build fails with "File not found":

• Check that all files referenced in SUMMARY.md exist
• Verify paths are relative to src/ directory

Links broken in generated site:

• Use relative links: [Link](./page.md) not absolute paths
• Check link anchors match actual heading IDs

Styles not applying:

• Custom CSS goes in theme/ directory
• See mdBook theme documentation

Search not working:

• Search is enabled by default in book.toml
• Rebuild if search index seems stale

Additional Resources

• mdBook Documentation
• Diataxis Framework
• Markdown Guide