Developer installation

This guide sets up a full development environment using VS Code’s Dev Containers feature. Everything needed to write code, run tests, lint, and build docs is pre-installed in the container: no manual dependency management required.

Prerequisites

Install the following before getting started:

Clone the repository

git clone https://github.com/Weeks-UNC/RNAvigate.git

Open in VS Code

Open the cloned directory in VS Code:

code RNAvigate

Or from within VS Code: File > Open Folder and select the RNAvigate directory.

Reopen in Dev Container

VS Code will detect the .devcontainer configuration and prompt you to reopen in the container.

  1. Click Reopen in Container in the notification that appears in the bottom-right corner of VS Code.

    Alternatively, press Ctrl+Shift+P (Cmd+Shift+P on macOS), type Dev Containers: Reopen in Container, and press Enter.

  2. The first time you open the container, Docker will build the image and install all dependencies. This may take a few minutes. Subsequent opens are much faster because the image is cached.

  3. Once the container is ready, VS Code reloads with the full development environment active and all extensions installed.

Tools in the Dev Container

The dev container is built on Python 3.12 and includes the following tools.

Python Environment

All dependencies are pre-installed in a virtual environment at /opt/venv and activated automatically in every terminal. RNAvigate itself is installed in editable mode, so changes to the source code take effect immediately without reinstalling.

uv

uv is the package manager for the project. Dependencies are declared in pyproject.toml and pinned in uv.lock. To add or update a dependency, edit pyproject.toml and run:

uv sync --extra dev --extra docs

The dev extra includes pytest, pytest-cov, ruff, and pre-commit. The docs extra includes sphinx, sphinx-autobuild, sphinx-rtd-theme, nbsphinx, and ipykernel.

Testing

Run the test suite with pytest:

pytest

Coverage reports can be generated with:

pytest --cov=rnavigate --cov-report=html

Linting and Formatting

Ruff handles both linting and formatting, and is configured to format Python files on save in VS Code. To run manually:

ruff check --fix .
ruff format .

Pre-commit Hooks

Pre-commit hooks run automatically on each git commit and enforce the following checks:

  • ruff: lints Python code and applies safe auto-fixes

  • ruff-format: formats Python code

  • uv-lock: keeps uv.lock in sync with pyproject.toml

  • nbstripout: strips output cells from notebooks before committing

  • pytest: runs the full test suite

To run all hooks manually without committing:

pre-commit run --all-files

Documentation

This documentation website is built with Sphinx. You can use sphinx-autobuild from the VS Code terminal to preview it locally.

cd docs/
make livehtml

If the build is successful, you will see a message like:

[sphinx-autobuild] Building...
...
...lots of messages about the build process...
...
build succeeded.
The HTML pages are in build.
[sphinx-autobuild] Serving on http://127.0.0.1:8000

Alt + click on the URL to open the docs in your browser. Changes to .rst or .ipynb files trigger an automatic rebuild. Type Ctrl + C in the terminal to stop the server when you’re done.

VS Code Extensions

The following extensions are installed automatically in the container:

  • Python (ms-python.python): Python language support

  • Pylance (ms-python.vscode-pylance): type checking and IntelliSense

  • Ruff (charliermarsh.ruff): inline linting and format-on-save

  • Jupyter (ms-toolsai.jupyter): Jupyter notebook support

  • Better Comments (aaron-bond.better-comments): styled code annotations

  • Markdown Preview Enhanced (shd101wyy.markdown-preview-enhanced): live Markdown preview

  • Text Tables (RomanPeshkov.vscode-text-tables): RST and Markdown table editing

  • VS Code Icons (vscode-icons-team.vscode-icons): file icons

  • Claude Code (Anthropic.claude-code): AI coding assistant