mggg · peterrrock2 · Dec 12, 2025 · May 6, 2025 · May 23, 2025 · Jul 8, 2025
diff --git a/.github/workflows/docs-pr-check.yml b/.github/workflows/docs-pr-check.yml
@@ -1,12 +1,21 @@
 name: "Pull Request Docs Check"
-on: 
-- pull_request
+
+on:
+  pull_request:
 
 jobs:
   docs:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v1
-    - uses: ammaraskar/sphinx-action@master
-      with:
-        docs-folder: "docs/"
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Build docs
+        run: make docs
diff --git a/.gitignore b/.gitignore
@@ -6,6 +6,9 @@ __pycache__/
 # C extensions
 *.so
 
+# dev stuff
+dev_files
+
 # Distribution / packaging
 .Python
 env/
@@ -83,4 +86,4 @@ TODO.md
 
 # Environment items
 .env
-.envrc
+.envrc
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -0,0 +1,6 @@
+repos:
+  - repo: https://github.com/psf/black
+    rev: 24.2.0
+    hooks:
+      - id: black
+        files: gerrytools/
diff --git a/MANIFEST.in b/MANIFEST.in
diff --git a/Makefile b/Makefile
@@ -0,0 +1,96 @@
+# Makefile for managing GerryChain development tasks using 'uv' virtual environment manager.
+
+PYTHON_VERSION = 3.11
+VENV_DIR ?= .venv
+PKG ?= gerrychain
+TEST_PATHS ?= tests
+
+.PHONY: help setup install dev install-docs test lint format precommit docs clean
+
+help:
+	@echo "Available targets:"
+	@echo "  setup         - Set up environment for full development including dev dependencies and pre-commit hooks"
+	@echo "  install       - Install the package"
+	@echo "  install-docs  - Install documentation dependencies"
+	@echo "  test          - Run the test suite"
+	@echo "  lint          - Run code linters"
+	@echo "  format        - Format the codebase"
+	@echo "  precommit     - Run pre-commit hooks"
+	@echo "  docs          - Build the documentation"
+	@echo "  clean         - Clean build artifacts"
+
+
+check_prereq:
+	@echo "Checking prerequisites..."
+	@if ! command -v uv > /dev/null 2>&1; then \
+		echo "Error: 'uv' is not installed. Please install it first using the following command:"; \
+		echo "    curl -LsSf https://astral.sh/uv/install.sh | sh"; \
+		exit 1; \
+	fi
+	@echo "'uv' is installed."
+
+setup: check_prereq
+	@echo "Setting up the development environment for GerryChain..."
+	@echo
+	uv python install $(PYTHON_VERSION)
+	@echo "Creating virtual environment and installing dev dependencies..."
+	uv sync --python $(PYTHON_VERSION) 
+	uv sync --all-groups
+	uv pip install -e .
+	uv run pre-commit install
+	@echo ""
+	@echo "Development environment setup complete!"
+
+install: check_prereq
+	@echo "Installing GerryChain package..."
+	uv sync --python $(PYTHON_VERSION)
+	uv pip install -e .
+
+install-docs: check_prereq
+	@echo "Installing GerryChain package with all just the documentation dependencies..."
+	uv sync --python $(PYTHON_VERSION)
+	uv sync --group docs
+	uv pip install -e .
+
+test:
+	@echo "Running test suite..."
+	uv run pytest -v $(TEST_PATHS)
+
+# Add this in later
+# type-check:
+# 	@echo "Running type checking with mypy..."
+# 	uv run mypy $(PKG) ${TEST_PATHS}
+
+format:
+	@echo "Formatting codebase with black..."
+	uv run isort $(PKG) $(TEST_PATHS)
+	uv run black $(PKG) $(TEST_PATHS)
+
+lint: 
+	@echo "Running linters (ruff)..."
+	uv run ruff check $(PKG) $(TEST_PATHS)
+
+precommit:
+	@echo "Running pre-commit hooks..."
+	uv run pre-commit install
+	uv run pre-commit run --all-files
+
+docs: install-docs
+	@echo "Building documentation..."
+	uv run sphinx-build -b html docs/ docs/_build
+
+clean:
+	@echo "Cleaning build artifacts..."
+	@rm -rf build/ \
+		dist/ \
+		*.egg-info \
+		.pytest_cache/ \
+		.mypy_cache/ \
+		.ruff_cache/ \
+		docs/_build/ \
+		$(VENV_DIR) \
+		.vscode/ \
+		.ipynb_checkpoints/ \
+		docs/build/
+	@find . -type d -name "__pycache__" -exec rm -rf {} +
+	@echo "Clean complete."
diff --git a/docs/Makefile b/docs/Makefile
diff --git a/docs/conf.py b/docs/conf.py
@@ -81,7 +81,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = 'en'
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -120,7 +120,7 @@
 #
 # html_sidebars = {}
 html_css_files = [
-    'css/custom.css',
+    "css/custom.css",
 ]
 
 
@@ -192,33 +192,6 @@
 
 autodoc_default_flags = ["members"]
 
-# -- Mock C libraries --------------------------------------------------------
-
-# RTD is unable to install libraries with C dependencies.
-# We're using the mock module to mock those away.
-
-MOCK_MODULES = [
-    "numpy",
-    "pandas",
-    "geopandas",
-    "matplotlib",
-    "matplotlib.pyplot",
-    # "networkx",
-    # "networkx.readwrite",
-    # "networkx.algorithms",
-    # "networkx.algorithms.shortest_paths",
-    # "networkx.algorithms.shortest_paths.weighted",
-    "shapely",
-    "shapely.ops",
-    "shapely.strtree",
-    "shapely.prep",
-    "shapely.prepared",
-    "shapely.validation",
-    "gerrychain.vendor.utm",
-]
-
-for module in MOCK_MODULES:
-    sys.modules[module] = mock.Mock()
 
 # -- Extension configuration -------------------------------------------------
 

diff --git a/docs/geo_settings.txt b/docs/geo_settings.txt
diff --git a/docs/index.rst b/docs/index.rst
@@ -37,7 +37,11 @@ repository, where `bug reports and feature requests`_, as well as
 .. _`contributions`: https://github.com/mggg/gerrychain/pulls
 
 
-.. include:: user/install.rst
+.. include:: user/install_header.rst
+
+For more detailed installation instructions, including instructions for
+setting up virtual environments, please see the following section:
+:doc:`user/install`.
 
 .. toctree::
     :caption: User Guide
@@ -82,4 +86,4 @@ MGGG for the 2019 MIT IAP course `Computational Approaches for Political Redistr
     :caption: Index
     :maxdepth: 4
 
-    full_ref
+    full_ref
diff --git a/docs/make.bat b/docs/make.bat
diff --git a/docs/requirements.txt b/docs/requirements.txt
diff --git a/docs/user/install.rst b/docs/user/install.rst
@@ -1,20 +1,4 @@
-Installation
-============
-
-Supported Python Versions
--------------------------
-
-The most recent version of GerryChain (as of April 2024) supports
-
-- Python 3.9
-- Python 3.10
-- Python 3.11
-- Python 3.12
-
-If you do not have one of these versions installed on you machine, we
-recommend that you go to the 
-`Python website <https://www.python.org/downloads/>`_ and
-download the installer for one of these versions. [1]_
+.. include:: ./install_header.rst
 
 .. admonition:: A Note For Windows Users
   :class: note
@@ -130,17 +114,6 @@ ready to install GerryChain.
 To install GerryChain from PyPI_, run ``pip install gerrychain`` from
 the command line. 
 
-If you plan on using GerryChain's GIS functions, such as computing
-adjacencies or reading in shapefiles, then run
-``pip install gerrychain[geo]`` from the command line.
-
-This approach sometimes fails due to compatibility issues between our
-different Python GIS dependencies, like ``geopandas``, ``pyproj``,
-``fiona``, and ``shapely``. If you run into this issue, try installing
-the dependencies using the 
-`geo_settings.txt <https://github.com/mggg/GerryChain/tree/main/docs/geo_settings.txt>`_
-file. To do this, run ``pip install -r geo_settings.txt`` from the
-command line.
 
 .. note::
 
@@ -151,10 +124,6 @@ command line.
   line.
 
 .. _PyPI: https://pypi.org/
-.. [1] Of course, if you are using a Linux system, you will either need to use your
-  system's package manager or install from source. You may also find luck installing
-  Python directly from the package manager if you find installing from source to be
-  troublesome.
 
 
 .. include:: ../repeated_subsections/reproducible_envs.rst
diff --git a/docs/user/install_header.rst b/docs/user/install_header.rst
@@ -0,0 +1,23 @@
+Installation
+============
+
+Supported Python Versions
+-------------------------
+
+The most recent version of GerryChain (as of April 2024) supports
+
+- Python 3.11
+- Python 3.12
+- Python 3.13
+
+If you do not have one of these versions installed on you machine, we
+recommend that you go to the 
+`Python website <https://www.python.org/downloads/>`_ and
+download the installer for one of these versions.
+
+Most users can install GerryChain using pip:
+
+.. code:: console
+
+    pip install gerrychain
+