Episode 05.b - Building and Distribution¶
📚 Documentation¶
README.md with Badges¶
Enhance your README with status badges:
# kir-pydemo
[](https://github.com/bmrc/kir-pydemo/actions)
[](https://codecov.io/gh/bmrc/kir-pydemo)
[](https://pypi.org/project/kir-pydemo/)
[](https://pypi.org/project/kir-pydemo/)
[](https://opensource.org/licenses/MIT)
A demonstration package for DNA sequence analysis.
## Features
- Calculate GC content of DNA sequences
- Generate reverse complement of DNA sequences
- Command-line interface for quick analysis
- FASTA file support
## Installation
```bash
pip install kir-pydemo
With optional dependencies:
Quick Start¶
from kir_pydemo import gc_content, reverse_complement
# Calculate GC content
gc = gc_content("ATGCATGC")
print(f"GC content: {gc}%") # GC content: 50.0%
# Get reverse complement
rev = reverse_complement("ATGC")
print(rev) # GCAT
Command Line¶
# Calculate GC content
kir-pydemo gc-content ATGCATGC
# Reverse complement
kir-pydemo reverse-complement ATGCATGC
Documentation¶
Full documentation available at https://kir-pydemo......
Contributing¶
Contributions welcome! Please read (Link to CONTRIBUTING.md)).
License¶
MIT License - see (link to LICENSE) file.
### MkDocs Material Documentation
For modern, beautiful documentation, use [MkDocs Material](https://squidfunk.github.io/mkdocs-material/):
**Why MkDocs Material?**
- ✅ **Beautiful by default** - Professional appearance out of the box
- ✅ **Markdown-based** - Write docs in familiar Markdown format
- ✅ **Fast and responsive** - Works great on all devices
- ✅ **Easy to customize** - Simple YAML configuration
- ✅ **GitHub Pages ready** - Deploy with one command
#### Step 1: Install MkDocs Material
Add to your `pyproject.toml`:
```toml
[project.optional-dependencies]
docs = [
"mkdocs-material>=9.5.0",
"mkdocstrings[python]>=0.24.0",
]
Install:
Step 2: Create Documentation Structure¶
# Initialize MkDocs
mkdocs new .
# This creates:
# mkdocs.yml - Configuration file
# docs/
# └── index.md - Homepage
Create additional documentation pages:
mkdir -p docs/guide docs/api
touch docs/guide/installation.md
touch docs/guide/quickstart.md
touch docs/guide/cli.md
touch docs/api/reference.md
Your structure should look like:
kir-pydemo/
├── docs/
│ ├── index.md # Homepage
│ ├── guide/
│ │ ├── installation.md # Installation guide
│ │ ├── quickstart.md # Quick start tutorial
│ │ └── cli.md # CLI reference
│ └── api/
│ └── reference.md # API documentation
├── mkdocs.yml # MkDocs configuration
├── src/
└── pyproject.toml
Step 3: Configure mkdocs.yml¶
Create a comprehensive configuration:
site_name: kir-pydemo
site_description: DNA sequence analysis tools
site_author: BMRC Training
site_url: https://yourusername.github.io/kir-pydemo
repo_name: yourusername/kir-pydemo
repo_url: https://github.com/yourusername/kir-pydemo
theme:
name: material
palette:
# Light mode
- scheme: default
primary: indigo
accent: indigo
toggle:
icon: material/brightness-7
name: Switch to dark mode
# Dark mode
- scheme: slate
primary: indigo
accent: indigo
toggle:
icon: material/brightness-4
name: Switch to light mode
features:
- navigation.tabs
- navigation.sections
- navigation.top
- search.highlight
- search.share
- content.code.copy
- content.code.annotate
markdown_extensions:
- pymdownx.highlight:
anchor_linenums: true
- pymdownx.inlinehilite
- pymdownx.snippets
- pymdownx.superfences
- pymdownx.tabbed:
alternate_style: true
- admonition
- pymdownx.details
plugins:
- search
- mkdocstrings:
handlers:
python:
paths: [src]
options:
docstring_style: numpy
show_source: true
show_root_heading: true
nav:
- Home: index.md
- User Guide:
- Installation: guide/installation.md
- Quick Start: guide/quickstart.md
- CLI Reference: guide/cli.md
- API Reference: api/reference.md
extra:
social:
- icon: fontawesome/brands/github
link: https://github.com/yourusername/kir-pydemo
Step 4: Write Documentation Pages¶
docs/index.md (Homepage):
# kir-pydemo
DNA sequence analysis tools for bioinformatics.
## Features
- 🧬 Calculate GC content of DNA sequences
- 🔄 Generate reverse complement
- 💻 Command-line interface
- 📁 FASTA file support
## Quick Example
```python
from kir_pydemo import gc_content, reverse_complement
# Calculate GC content
gc = gc_content("ATGCATGC")
print(f"GC content: {gc}%") # 50.0%
# Reverse complement
rev = reverse_complement("ATGC")
print(rev) # GCAT
Installation¶
For more details, see the (Link to Installation.MD or similar)).
**`docs/guide/installation.md`**:
```markdown
# Installation
## Basic Installation
Install kir-pydemo using pip:
```bash
pip install kir-pydemo
Optional Dependencies¶
FASTA Support¶
For reading FASTA files:
Development¶
For development with testing and linting tools:
All Features¶
Install everything:
From Source¶
Clone and install from source:
**`docs/api/reference.md`** (API Documentation with mkdocstrings):
```markdown
# API Reference
## Sequence Analysis
::: kir_pydemo.sequence
options:
show_root_heading: true
show_source: true
## File I/O
::: kir_pydemo.io
options:
show_root_heading: true
show_source: true
The kir_pydemo.sequence syntax automatically pulls docstrings from your code!
Step 5: Build and Serve Locally¶
Changes to your docs auto-reload in the browser!
Step 6: Deploy to GitHub Pages¶
Option 1: Manual deployment
Option 2: Automated with GitHub Actions
Create .github/workflows/docs.yml:
name: Documentation
on:
push:
branches:
- main
permissions:
contents: write
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: '3.11'
- name: Install dependencies
run: |
pip install -e ".[docs]"
- name: Deploy docs
run: mkdocs gh-deploy --force
Now docs deploy automatically on every push to main!
Enable GitHub Pages:
- Go to repository Settings → Pages
- Source: Deploy from a branch
- Branch:
gh-pages/root - Save
Your docs will be live at: https://yourusername.github.io/kir-pydemo