Skip to content

Commit 03cff01

Browse files
docs: simplify README and fix mkdocs configuration
- Simplify README, move details to mkdocs site - Add MIT license file - Fix mkdocs emoji extension for material icons - Remove expandable navigation πŸ€– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent d69386e commit 03cff01

File tree

3 files changed

+32
-116
lines changed

3 files changed

+32
-116
lines changed

β€ŽLICENSEβ€Ž

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 RNA Bioscience Initiative
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

β€ŽREADME.mdβ€Ž

Lines changed: 8 additions & 114 deletions
Original file line numberDiff line numberDiff line change
@@ -1,141 +1,35 @@
11
# charmer
22

3-
A terminal user interface (TUI) for monitoring Snakemake pipelines running on HPC clusters.
3+
A terminal user interface (TUI) for monitoring Snakemake pipelines on HPC clusters.
44

55
![Charmer Demo](docs/images/demo.gif)
66

77
## Features
88

9-
- **Real-time monitoring** of Snakemake pipelines on SLURM and LSF clusters
10-
- **Unified view** merging data from scheduler queries and Snakemake metadata
11-
- **Interactive TUI** with vim-style navigation
12-
- **Filtering & sorting** by job status, rule name, or time
13-
- **Log viewer** for examining job output
14-
- **Cross-platform** support for Linux and macOS
9+
- Real-time monitoring of Snakemake pipelines on SLURM and LSF clusters
10+
- Interactive TUI with vim-style navigation
11+
- Filtering, sorting, and log viewing
1512

1613
## Installation
1714

18-
### From source
19-
2015
```bash
21-
# Clone the repository
22-
git clone https://github.com/rnabioco/charmer.git
23-
cd charmer
24-
25-
# Build with cargo
26-
cargo build --release
27-
28-
# Install to ~/.cargo/bin
29-
cargo install --path crates/charmer
16+
cargo install --git https://github.com/rnabioco/charmer.git
3017
```
3118

32-
### Using pixi (for development)
33-
34-
```bash
35-
pixi install
36-
pixi run build
37-
```
38-
39-
## Usage
19+
## Quick Start
4020

4121
```bash
4222
# Monitor current directory
4323
charmer
4424

4525
# Monitor specific directory
4626
charmer /path/to/pipeline
47-
48-
# With options
49-
charmer --poll-interval 10 --theme dark /path/to/pipeline
5027
```
5128

52-
### CLI Options
53-
54-
| Option | Default | Description |
55-
|--------|---------|-------------|
56-
| `--poll-interval` | 5 | Seconds between scheduler queries |
57-
| `--run-uuid` | - | Filter to specific Snakemake run |
58-
| `--theme` | dark | Color theme (dark/light) |
59-
| `--history-hours` | 24 | Show completed jobs from last N hours |
60-
61-
### Keyboard Shortcuts
62-
63-
| Key | Action |
64-
|-----|--------|
65-
| `j` / `↓` | Move down |
66-
| `k` / `↑` | Move up |
67-
| `g` / `Home` | Go to first job |
68-
| `G` / `End` | Go to last job |
69-
| `f` | Cycle filter (All/Running/Failed/Pending/Completed) |
70-
| `s` | Cycle sort (Status/Rule/Time) |
71-
| `l` / `Enter` | View job logs |
72-
| `F` | Toggle follow mode in logs |
73-
| `?` | Show help |
74-
| `q` / `Ctrl+C` | Quit |
75-
76-
## Supported Schedulers
77-
78-
### SLURM
79-
80-
Charmer queries SLURM using:
81-
- `squeue` for active jobs
82-
- `sacct` for job history
83-
84-
Jobs are correlated with Snakemake using the comment field format:
85-
`rule_{rulename}_wildcards_{wildcards}`
86-
87-
### LSF
88-
89-
Charmer queries LSF using:
90-
- `bjobs` for active jobs
91-
- `bhist` for job history
29+
## Documentation
9230

93-
## How It Works
94-
95-
Charmer combines data from multiple sources:
96-
97-
1. **Snakemake metadata** (`.snakemake/metadata/`) - Job inputs, outputs, shell commands
98-
2. **Scheduler queries** - Job status, resource usage, timing
99-
3. **Log files** (`.snakemake/slurm_logs/`) - Job output and errors
100-
101-
Data is merged using rule names and timing windows to correlate jobs across sources.
102-
103-
## Development
104-
105-
```bash
106-
# Install dependencies
107-
pixi install
108-
109-
# Run tests
110-
cargo test
111-
112-
# Run with debug logging
113-
RUST_LOG=debug cargo run -- .
114-
115-
# Build documentation
116-
pixi run docs
117-
```
118-
119-
### Project Structure
120-
121-
```
122-
charmer/
123-
β”œβ”€β”€ crates/
124-
β”‚ β”œβ”€β”€ charmer/ # Main binary
125-
β”‚ β”œβ”€β”€ charmer-cli/ # CLI argument parsing
126-
β”‚ β”œβ”€β”€ charmer-core/ # Snakemake metadata parsing
127-
β”‚ β”œβ”€β”€ charmer-slurm/ # SLURM integration
128-
β”‚ β”œβ”€β”€ charmer-lsf/ # LSF integration
129-
β”‚ β”œβ”€β”€ charmer-state/ # Unified job state
130-
β”‚ └── charmer-monitor/ # TUI components
131-
β”œβ”€β”€ docs/ # Documentation
132-
└── tests/ # Integration tests
133-
```
31+
Full documentation is available at **[rnabioco.github.io/charmer](https://rnabioco.github.io/charmer)**.
13432

13533
## License
13634

13735
MIT License - see [LICENSE](LICENSE) for details.
138-
139-
## Contributing
140-
141-
Contributions welcome! Please read our [contributing guide](CONTRIBUTING.md) first.

β€Žmkdocs.ymlβ€Ž

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,8 +22,6 @@ theme:
2222
features:
2323
- navigation.instant
2424
- navigation.tracking
25-
- navigation.sections
26-
- navigation.expand
2725
- toc.follow
2826
- content.code.copy
2927
- content.code.annotate
@@ -43,6 +41,9 @@ markdown_extensions:
4341
- pymdownx.superfences
4442
- pymdownx.tabbed:
4543
alternate_style: true
44+
- pymdownx.emoji:
45+
emoji_index: !!python/name:material.extensions.emoji.twemoji
46+
emoji_generator: !!python/name:material.extensions.emoji.to_svg
4647
- admonition
4748
- pymdownx.details
4849
- attr_list

0 commit comments

Comments
Β (0)