Skip to content

Commit 2d4a2db

Browse files
semenkosemenko
committed
Update to support Sphinx docs?
1 parent c323093 commit 2d4a2db

File tree

8 files changed

+644
-39
lines changed

8 files changed

+644
-39
lines changed

‎.github/workflows/docs.yml‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
name: Build and Deploy Documentation
2+
3+
on:
4+
push:
5+
branches: [ main, master ]
6+
pull_request:
7+
branches: [ main, master ]
8+
9+
permissions:
10+
contents: read
11+
pages: write
12+
id-token: write
13+
14+
concurrency:
15+
group: "pages"
16+
cancel-in-progress: false
17+
18+
jobs:
19+
build:
20+
runs-on: ubuntu-latest
21+
22+
steps:
23+
- name: Checkout
24+
uses: actions/checkout@v4
25+
26+
- name: Setup Python
27+
uses: actions/setup-python@v4
28+
with:
29+
python-version: '3.11'
30+
31+
- name: Install dependencies
32+
run: |
33+
python -m pip install --upgrade pip
34+
pip install -r docs/requirements.txt
35+
36+
- name: Build documentation
37+
run: |
38+
cd docs
39+
sphinx-build -b html . _build/html
40+
41+
- name: Setup Pages
42+
uses: actions/configure-pages@v3
43+
if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master'
44+
45+
- name: Upload artifact
46+
uses: actions/upload-pages-artifact@v2
47+
if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master'
48+
with:
49+
path: docs/_build/html
50+
51+
deploy:
52+
environment:
53+
name: github-pages
54+
url: ${{ steps.deployment.outputs.page_url }}
55+
runs-on: ubuntu-latest
56+
needs: build
57+
if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master'
58+
59+
steps:
60+
- name: Deploy to GitHub Pages
61+
id: deployment
62+
uses: actions/deploy-pages@v2

‎README.md‎

Lines changed: 39 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -5,27 +5,25 @@
55
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
66
[![Platform: Linux](https://img.shields.io/badge/platform-Linux-blue.svg)](https://www.linux.org/)
77
[![Super-Linter](https://github.com/semenko/serpent-methylation-pipeline/actions/workflows/linter.yml/badge.svg)](https://github.com/marketplace/actions/super-linter)
8+
[![Documentation](https://github.com/semenko/serpent-methylation-pipeline/actions/workflows/docs.yml/badge.svg)](https://semenko.github.io/serpent-methylation-pipeline/)
89

910
<img src="serpent-logo.png" width="500px" alt="Serpent Pipeline Logo" />
1011

1112
A standardized, reproducible pipeline to process WGBS bisulfite & EM-seq data. This goes from .fastq to methylation calls (via [biscuit](https://github.com/huishenlab/biscuit)) and includes extensive QC and plotting, using a Snakemake pipeline.
1213

13-
At a high level, this pipeline reproducibly:
14-
- Builds a reference genome
15-
- Trims & (minimally) filters reads
16-
- Aligns & calls methylation using [biscuit](https://github.com/huishenlab/biscuit)
17-
- Flags non-converted reads
18-
- Generates standardized outputs & QC including
19-
- [FastQC](https://www.bioinformatics.babraham.ac.uk/projects/fastqc/)
20-
- [fastp](https://github.com/OpenGene/fastp)
21-
- Biscuit QC
22-
- [samtools stats](https://github.com/samtools/samtools)
23-
- [MethylDackel mbias plots](https://github.com/dpryan79/MethylDackel)
24-
- [Goleft covplots](https://github.com/brentp/goleft)
25-
- epibed/epiread files
26-
- Runs [multiqc](https://multiqc.info) across entire projects
14+
## 📖 Documentation
15+
16+
**[View the complete documentation](https://semenko.github.io/serpent-methylation-pipeline/)**
2717

28-
## Getting Started
18+
The documentation includes:
19+
- Detailed installation instructions
20+
- Configuration guide
21+
- Usage examples
22+
- Pipeline technical details
23+
- Troubleshooting guide
24+
- API reference
25+
26+
## Quick Start
2927

3028
This pipeline is designed to be straightforward:
3129
1. Clone this repository and open the directory:
@@ -37,42 +35,44 @@ This pipeline is designed to be straightforward:
3735
```
3836
mamba install -c bioconda -c conda-forge snakemake snakemake-storage-plugin-http
3937
```
40-
4. (Optional) Create a separate conda environment for pipeline dependencies:
38+
3. (Optional) Create a separate conda environment for pipeline dependencies:
4139
```
4240
mamba env create -n serpent_pipeline_env -f workflow/envs/env.yaml
41+
conda activate serpent_pipeline_env
4342
```
44-
Then activate it with:
43+
4. Test the pipeline:
4544
```
46-
conda activate serpent_pipeline_env
45+
snakemake --cores 4 --use-conda --dry-run
4746
```
4847

49-
### Test Run
50-
Use:
51-
```
52-
nice snakemake --cores 4 --use-conda --printshellcmds --rerun-incomplete --rerun-triggers mtime --keep-going --dry-run
53-
```
54-
to quickly validate the pipeline and see what would be executed. Remove `--dry-run` to run the full process.
55-
56-
After removing the `--dry-run` flag, this will download reference genomes and build indices.
57-
58-
### Mac OS X Compatibility
48+
For detailed instructions, see the [Installation Guide](https://semenko.github.io/serpent-methylation-pipeline/installation.html).
5949

60-
Unfortunately, critical dependencies don't support Mac OS architectures yet (e.g., `bwa-mem2` only supports `linux-aarch64`), though this might be supported using `brew`. Please open an issue or submit a PR if you're able to improve this situation! :smiley:
50+
## Features
6151

62-
### Data Definition
52+
At a high level, this pipeline reproducibly:
53+
- Builds a reference genome
54+
- Trims & (minimally) filters reads
55+
- Aligns & calls methylation using [biscuit](https://github.com/huishenlab/biscuit)
56+
- Flags non-converted reads
57+
- Generates standardized outputs & QC including
58+
- [FastQC](https://www.bioinformatics.babraham.ac.uk/projects/fastqc/)
59+
- [fastp](https://github.com/OpenGene/fastp)
60+
- Biscuit QC
61+
- [samtools stats](https://github.com/samtools/samtools)
62+
- [MethylDackel mbias plots](https://github.com/dpryan79/MethylDackel)
63+
- [Goleft covplots](https://github.com/brentp/goleft)
64+
- epibed/epiread files
65+
- Runs [multiqc](https://multiqc.info) across entire projects
6366

67+
## Support
6468

65-
### Expected Output
69+
- **Documentation**: [https://semenko.github.io/serpent-methylation-pipeline/](https://semenko.github.io/serpent-methylation-pipeline/)
70+
- **Issues**: [GitHub Issues](https://github.com/semenko/serpent-methylation-pipeline/issues)
71+
- **Discussions**: [GitHub Discussions](https://github.com/semenko/serpent-methylation-pipeline/discussions)
6672

67-
Raw data files from [data](../data) are processed and analyzed by this snakemake workflow. Within each project directory, the output is (roughly) structured as:
73+
## Contributing
6874

69-
SAMPLE_01/ # e.g. melanoma / crc / healthy, etc.
70-
│ SAMPLE.bam # The final alignment file
71-
| SAMPLE.bam.bai # (and its index)
72-
|── biscuit_qc/ # biscuit QC.sh text files
73-
|── epibeds/ # epibed files (bgzip-compressed & tabix-indexed)
74-
├── fastp/ # fastp statistics & logs
75-
├── fastqc/ # fastqc graphs
75+
We welcome contributions! Please see the [Contributing Guide](https://semenko.github.io/serpent-methylation-pipeline/contributing.html) in our documentation.
7676
├── goleft/ # goleft coverage plots
7777
├── logs/ # runlogs from each pipeline component
7878
├── methyldackel/ # mbias plots

‎docs/conf.py‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
# For the full list of built-in configuration values, see:
3+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
4+
5+
import os
6+
import sys
7+
8+
# -- Project information -----------------------------------------------------
9+
project = 'Serpent Methylation Pipeline'
10+
copyright = '2024, Nick Semenkovich'
11+
author = 'Nick Semenkovich'
12+
release = '1.0.0'
13+
14+
# -- General configuration ---------------------------------------------------
15+
extensions = [
16+
'sphinx.ext.autodoc',
17+
'sphinx.ext.viewcode',
18+
'sphinx.ext.napoleon',
19+
'sphinx.ext.intersphinx',
20+
'sphinx.ext.githubpages',
21+
'myst_parser',
22+
]
23+
24+
# Add any paths that contain templates here, relative to this directory.
25+
templates_path = ['_templates']
26+
27+
# List of patterns, relative to source directory, that match files and
28+
# directories to ignore when looking for source files.
29+
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
30+
31+
# -- Options for HTML output -------------------------------------------------
32+
html_theme = 'sphinx_rtd_theme'
33+
html_static_path = ['_static']
34+
35+
# Theme options
36+
html_theme_options = {
37+
'canonical_url': '',
38+
'analytics_id': '',
39+
'logo_only': False,
40+
'display_version': True,
41+
'prev_next_buttons_location': 'bottom',
42+
'style_external_links': False,
43+
'vcs_pageview_mode': '',
44+
'style_nav_header_background': '#2980B9',
45+
'collapse_navigation': True,
46+
'sticky_navigation': True,
47+
'navigation_depth': 4,
48+
'includehidden': True,
49+
'titles_only': False
50+
}
51+
52+
# Add logo
53+
html_logo = '../serpent-logo.png'
54+
55+
# Intersphinx mapping
56+
intersphinx_mapping = {
57+
'python': ('https://docs.python.org/3/', None),
58+
'snakemake': ('https://snakemake.readthedocs.io/en/stable/', None),
59+
}
60+
61+
# MyST configuration
62+
myst_enable_extensions = [
63+
"amsmath",
64+
"colon_fence",
65+
"deflist",
66+
"dollarmath",
67+
"html_admonition",
68+
"html_image",
69+
"linkify",
70+
"replacements",
71+
"smartquotes",
72+
"substitution",
73+
"tasklist",
74+
]

0 commit comments

Comments
 (0)