Migrate documentation from Sphinx to MkDocs

.gitignore

@@ -89,8 +89,8 @@ instance/
 # Scrapy stuff:
 .scrapy
 
-# Sphinx documentation
-docs/_build/
+# MkDocs build output
+site/
 
 # PyBuilder
 .pybuilder/
@@ -198,6 +198,10 @@ cython_debug/
 # Cursor rules directory
 .cursor/rules/
 
+### Claude Code ###
+.claude/
+CLAUDE.md
+
 ### Python Patch ###
 # Poetry local configuration file - https://python-poetry.org/docs/configuration/#local-configuration
 poetry.toml
@@ -214,3 +218,5 @@ data/compressed/*mzML.gz
 
 # Ignore example results directory to avoid large files
 examples/results/
+
+.DS_Store

.readthedocs.yaml

@@ -11,10 +11,5 @@ python:
     - method: pip
       path: .
 
-sphinx:
-  configuration: docs/source/conf.py
-  #fail_on_warning: true
-
-formats:
-  - pdf
-  - epub
+mkdocs:
+  configuration: mkdocs.yml

README.md

@@ -1,6 +1,8 @@
 # OptiMHC
 
-**OptiMHC** is an optimum rescoring pipeline for immunopeptidomics data. It enhances peptide identification by integrating multiple feature generators and machine learning-based rescoring.
+**An optimum rescoring pipeline for immunopeptidomics data that significantly enhances peptide identification performance.**
+
+OptiMHC integrates multiple rescoring features with machine learning-based rescoring to maximize the number of confidently identified peptides from mass spectrometry experiments.
 
 ## Quick Start
 

docs/api/cli.md

@@ -0,0 +1,5 @@
+# CLI
+
+::: optimhc.cli
+    options:
+      members: true

docs/api/core.md

@@ -0,0 +1,37 @@
+# Core
+
+## Config
+
+::: optimhc.core.config
+    options:
+      members: true
+
+## Pipeline
+
+::: optimhc.core.pipeline
+    options:
+      members: true
+
+## Feature Generation
+
+::: optimhc.core.feature_generation
+    options:
+      members: true
+
+## PSM Container
+
+::: optimhc.psm_container
+    options:
+      members: true
+
+## Logging
+
+::: optimhc.core.logging_helper
+    options:
+      members: true
+
+## Utilities
+
+::: optimhc.utils
+    options:
+      members: true

docs/api/features.md

@@ -0,0 +1,55 @@
+# Feature Generators
+
+## Base Class
+
+::: optimhc.feature_generator.base_feature_generator
+    options:
+      members: true
+
+## Basic
+
+::: optimhc.feature_generator.basic
+    options:
+      members: true
+
+## Spectral Similarity
+
+::: optimhc.feature_generator.spectral_similarity
+    options:
+      members: true
+
+## DeepLC
+
+::: optimhc.feature_generator.DeepLC
+    options:
+      members: true
+
+## Overlapping Peptide
+
+::: optimhc.feature_generator.overlapping_peptide
+    options:
+      members: true
+
+## PWM
+
+::: optimhc.feature_generator.PWM
+    options:
+      members: true
+
+## MHCflurry
+
+::: optimhc.feature_generator.mhcflurry
+    options:
+      members: true
+
+## NetMHCpan
+
+::: optimhc.feature_generator.netMHCpan
+    options:
+      members: true
+
+## NetMHCIIpan
+
+::: optimhc.feature_generator.netMHCIIpan
+    options:
+      members: true

docs/api/index.md

@@ -0,0 +1,14 @@
+# API Reference
+
+This section provides auto-generated documentation for all OptiMHC modules and classes.
+
+## Modules
+
+| Module | Description |
+|---|---|
+| [Core](core.md) | Configuration, pipeline orchestration, PSM container, and logging |
+| [I/O](io.md) | Input parsers for PepXML, PIN, and mzML formats |
+| [Feature Generators](features.md) | Base class and all feature implementations |
+| [Rescoring](rescore.md) | Mokapot integration and machine learning models |
+| [Visualization](visualization.md) | Plotting functions for results and diagnostics |
+| [CLI](cli.md) | Command-line interface |

docs/api/io.md

@@ -0,0 +1,25 @@
+# I/O
+
+## Parser Package
+
+::: optimhc.parser
+    options:
+      members: true
+
+## PepXML Parser
+
+::: optimhc.parser.pepxml
+    options:
+      members: true
+
+## PIN Parser
+
+::: optimhc.parser.pin
+    options:
+      members: true
+
+## mzML Parser
+
+::: optimhc.parser.mzml
+    options:
+      members: true

docs/api/rescore.md

@@ -0,0 +1,13 @@
+# Rescoring
+
+## Mokapot Integration
+
+::: optimhc.rescore.mokapot
+    options:
+      members: true
+
+## Models
+
+::: optimhc.rescore.model
+    options:
+      members: true

docs/api/visualization.md

@@ -0,0 +1,23 @@
+# Visualization
+
+::: optimhc.visualization
+    options:
+      members: true
+
+## Q-value Plots
+
+::: optimhc.visualization.plot_roc
+    options:
+      members: true
+
+## Feature Plots
+
+::: optimhc.visualization.plot_features
+    options:
+      members: true
+
+## Target/Decoy Distribution
+
+::: optimhc.visualization.plot_tdc_distribution
+    options:
+      members: true

docs/development/index.md

@@ -0,0 +1,59 @@
+# Development
+
+This page covers how to set up a development environment for contributing to OptiMHC.
+
+## Clone the Repository
+
+```bash
+git clone https://github.com/5h4ng/OptiMHC.git
+cd OptiMHC
+```
+
+## Install Dependencies
+
+OptiMHC uses [uv](https://docs.astral.sh/uv/) for dependency management (recommended):
+
+```bash
+uv sync --locked --group dev
+```
+
+Alternatively, using pip:
+
+```bash
+pip install -e ".[gui]"
+pip install pytest ruff pre-commit
+```
+
+## Running Tests
+
+```bash
+uv run pytest                              # All tests
+uv run pytest tests/test_psm_container.py  # Single file
+uv run pytest tests/ -k "test_config"      # Filter by name
+```
+
+## Linting and Formatting
+
+OptiMHC uses [Ruff](https://docs.astral.sh/ruff/) for linting and formatting:
+
+```bash
+uv run ruff check .          # Lint
+uv run ruff format .         # Format
+uv run ruff format --check . # Check without modifying
+```
+
+Configuration: `line-length = 99`, rules `["E", "F", "I"]` (pycodestyle errors, pyflakes, isort). `E501` (line too long) is ignored. Ruff excludes `docs/`, `examples/`, and `optimhc/gui/`.
+
+## Pre-commit Hooks
+
+```bash
+uv run pre-commit install              # Install hooks
+uv run pre-commit run --all-files      # Run all hooks manually
+```
+
+## Building Documentation
+
+```bash
+mkdocs serve   # Local preview at http://127.0.0.1:8000
+mkdocs build   # Static build to site/
+```

docs/getting-started/installation.md

@@ -0,0 +1,77 @@
+# Installation
+
+## Requirements
+
+- Python >= 3.10, < 3.13
+
+## Install from Source
+
+```bash
+git clone https://github.com/5h4ng/OptiMHC.git
+cd OptiMHC
+pip install -e .
+```
+
+Or using **uv** (recommended for development):
+
+```bash
+git clone https://github.com/5h4ng/OptiMHC.git
+cd OptiMHC
+uv sync --locked
+```
+
+!!! note "PyPI"
+    PyPI distribution is not yet available. For now, install from source as shown above.
+
+## NetMHCpan / NetMHCIIpan Setup
+
+Most OptiMHC dependencies are installed automatically via pip. The only exceptions are **NetMHCpan** and **NetMHCIIpan**, which are standalone executables that must be downloaded and installed manually.
+
+### 1. Download
+
+- [NetMHCpan 4.1](https://services.healthtech.dtu.dk/services/NetMHCpan-4.1/) (MHC Class I)
+- [NetMHCIIpan 4.3](https://services.healthtech.dtu.dk/services/NetMHCIIpan-4.3/) (MHC Class II)
+
+Both require a license from DTU Health Tech (free for academic use).
+
+### 2. Install and Add to PATH
+
+After downloading and extracting, follow the installation instructions provided by DTU. Then make sure the executables are accessible from your shell:
+
+=== "Linux / macOS"
+
+    ```bash
+    # Add to your ~/.bashrc or ~/.zshrc:
+    export PATH="/path/to/netMHCpan-4.1:$PATH"
+    export PATH="/path/to/netMHCIIpan-4.3:$PATH"
+    ```
+
+=== "Verify"
+
+    ```bash
+    which netMHCpan       # Should print the path to the executable
+    which netMHCIIpan     # Should print the path to the executable
+    ```
+
+OptiMHC calls these tools via the [mhctools](https://github.com/openvax/mhctools) library, which invokes `netMHCpan` and `netMHCIIpan` as command-line programs. If they are not on your `PATH`, the prediction step will fail with a "command not found" error.
+
+### 3. Test the Installation
+
+```bash
+netMHCpan -v          # Should print the version number
+netMHCIIpan -v        # Should print the version number
+```
+
+!!! tip
+    If you do not need MHC binding predictions, you can skip this step entirely and use OptiMHC with other features (Basic, SpectralSimilarity, DeepLC, PWM, OverlappingPeptide, MHCflurry) — all of which are installed via pip.
+
+## Verify OptiMHC Installation
+
+```bash
+optimhc --help
+```
+
+You should see the available commands: `pipeline`, `experiment`, and `gui`.
+
+!!! note "GUI"
+    The Streamlit GUI is currently under development. <!-- todo -->