Python Virtual Environment Setup

Set up a Python virtual environment for local MkDocs development and documentation builds.

---

Prerequisites

• Python 3.11 or higher installed
• Git repository cloned locally (worktree workflow is mandatory for feature work — see GitHub flow)
• Terminal access (bash/zsh for macOS/Linux, PowerShell for Windows)

---

Setup Steps

1. Navigate to Repository Root

The base clone always stays on main; feature work happens inside worktrees/<branch-name>/. Run pwd and git branch --show-current first to confirm where you are. The venv lives at the repository root of whichever checkout (main clone or worktree) you are working in.

cd /path/to/ohemr-epic-megadoc

2. Create Virtual Environment

python3 -m venv .venv

This creates a .venv/ directory (dotted, matching the repo convention and .gitignore) in your repository root containing an isolated Python environment.

3. Activate Virtual Environment

macOS / Linux:

source .venv/bin/activate

Windows (PowerShell):

.\.venv\Scripts\Activate.ps1

Windows (Command Prompt):

.\.venv\Scripts\activate.bat

When activated, your terminal prompt will show (.venv) prefix:

(.venv) user@hostname:~/ohemr-epic-megadoc$

4. Install Dependencies

With the virtual environment activated, install all required packages from requirements.txt:

pip install -r requirements.txt

This installs MkDocs, Material theme, and all necessary extensions for building the documentation site.

---

Verification

Verify the installation by checking MkDocs version:

mkdocs --version

Expected output:

mkdocs, version 1.6.1 from /path/to/.venv/lib/python3.x/site-packages/mkdocs (Python 3.x)

Test serving the documentation locally:

mkdocs serve

Navigate to http://127.0.0.1:8000 in your browser to view the site.

---

Working with the Virtual Environment

Activate

Always activate the virtual environment before working on documentation:

source .venv/bin/activate  # macOS/Linux

Deactivate

When finished, deactivate to return to your system Python:

deactivate

Update Dependencies

If requirements.txt is updated, refresh your virtual environment:

source .venv/bin/activate
pip install -r requirements.txt --upgrade

---

Common Commands

---

Troubleshooting

Virtual Environment Not Found

Symptom: source: no such file or directory: .venv/bin/activate

Solution: Create the virtual environment first:

python3 -m venv .venv

Permission Errors on Windows

Symptom: Activate.ps1 cannot be loaded because running scripts is disabled

Solution: Allow script execution (run PowerShell as Administrator):

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

MkDocs Command Not Found

Symptom: command not found: mkdocs after installing dependencies

Solution: Ensure virtual environment is activated:

source .venv/bin/activate
which mkdocs  # Should show path inside .venv/

Package Installation Failures

Symptom: Errors during pip install -r requirements.txt

Solution: Upgrade pip first:

pip install --upgrade pip
pip install -r requirements.txt

---

Best Practices

• Always activate the virtual environment before running MkDocs commands
• Never commit the .venv/ directory to git (already in .gitignore)
• Keep dependencies updated by periodically running pip install -r requirements.txt --upgrade
• Use separate virtual environments for different Python projects to avoid conflicts
• Re-create the venv per worktree if you keep multiple worktrees active simultaneously; sharing a single .venv across worktrees works in practice but obscures dependency drift between branches

---

Next Steps

1. ✅ Set up virtual environment
2. ✅ Install dependencies
3. ✅ Verify MkDocs installation
4. 📖 Review Writing Standards
5. 🚀 Start contributing to documentation

---

Additional Resources

• Python venv Documentation
• MkDocs Documentation
• Material for MkDocs
• Contributing Overview