feat: new documentation and CI improvements (#15)

Signed-off-by: Will Killian <william.killian@outlook.com>

Author: willkill07

.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.{py,pyi}]
+indent_size = 4

.github/workflows/docs.yml

@@ -1,52 +1,60 @@
+# Publish Fern docs to https://mucsci-scheduler.docs.buildwithfern.com
+# Requires repository secret FERN_TOKEN (see Fern Dashboard / `fern token`).
+
 name: documentation
 
 on:
   push:
-    tags:
-      - '*'
+    branches:
+      - main
+    paths:
+      - "fern/**"
+      - "scripts/**"
+      - "src/scheduler/**"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
 
 permissions:
   contents: read
 
 jobs:
-  build:
+  publish:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@v6
         with:
           persist-credentials: false
-      
+
       - name: Set up Python
         uses: actions/setup-python@v6
         with:
-          python-version: '3.12'
+          python-version: "3.12"
 
       - name: Install uv
         uses: astral-sh/setup-uv@v7
 
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
       - name: Install the project
-        run: uv sync --locked --all-extras --dev
+        run: uv sync --locked --group dev
 
-      - name: Build the documentation
-        run: uv run pdoc -o docs/ scheduler
+      - name: Generate OpenAPI, JSON Schema, and Python API reference
+        run: |
+          uv run python scripts/export_openapi.py
+          uv run python scripts/export_config_schema.py
+          uv run python scripts/gen_python_api_mdx.py
 
-      - name: Upload the documentation
-        uses: actions/upload-pages-artifact@v4
-        with:
-          path: docs/
+      - name: Install Fern CLI
+        run: npm install -g fern-api@4.35.0
 
-  # Deploy the artifact to GitHub pages.
-  # This is a separate job so that only actions/deploy-pages has the necessary permissions.
-  deploy:
-    needs: build
-    runs-on: ubuntu-latest
-    permissions:
-      pages: write
-      id-token: write
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    steps:
-      - id: deployment
-        uses: actions/deploy-pages@v4
+      - name: Fern check
+        run: fern check
+
+      - name: Publish docs to Fern
+        env:
+          FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
+        run: fern generate --docs

.github/workflows/linting.yml

@@ -5,14 +5,16 @@ on:
     branches:
       - main
   pull_request:
+    branches:
+      - main
 
 jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@v6
-        
+
       - name: Set up Python
         uses: actions/setup-python@v6
         with:
@@ -22,10 +24,27 @@ jobs:
         uses: astral-sh/setup-uv@v7
 
       - name: Install the project
-        run: uv sync --locked --all-extras --dev
+        run: uv sync --locked --group dev
 
-      - name: Run Ruff check
-        run: uv run ruff check . --output-format=github
+      - name: Run prek (lint, format, typecheck, file checks)
+        run: uv run prek run --all-files
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Install the project
+        run: uv sync --locked --group dev
 
-      - name: Run Ty check
-        run: uv run ty check .
+      - name: Run tests
+        run: uv run pytest

.github/workflows/publish.yml

@@ -18,7 +18,7 @@ jobs:
         uses: actions/checkout@v6
         with:
           persist-credentials: false
-      
+
       - name: Set up Python
         uses: actions/setup-python@v6
         with:
@@ -28,7 +28,7 @@ jobs:
         uses: astral-sh/setup-uv@v7
 
       - name: Install the project
-        run: uv sync --locked --all-extras --dev
+        run: uv sync --locked --group dev
 
       - name: Build the package
         run: uv build

.gitignore

@@ -1,16 +1,24 @@
 .venv
 
+.env
+.env.*
+!.env.example
+
 **/__pycache__
 **/*.pyc
 **/*egg-info*
 
 dist/
 .ruff_cache/
 
+.coverage
+htmlcov/
+
 **/*~
 **/#*#
 
 **/*.json
 !example.json
+!tests/fixtures/**/*.json
 
 **/.DS_Store

.pre-commit-config.yaml

@@ -1,11 +1,28 @@
 repos:
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v6.0.0
+  hooks:
+    - id: trailing-whitespace
+    - id: end-of-file-fixer
+    - id: check-yaml
+    - id: check-json
+    - id: check-toml
+    - id: check-merge-conflict
+    - id: detect-private-key
+    - id: mixed-line-ending
+    - id: check-added-large-files
+      args: [--maxkb=500]
+    - id: check-ast
+      types: [python]
+    - id: debug-statements
+      types: [python]
 - repo: https://github.com/astral-sh/ruff-pre-commit
   # Ruff version.
-  rev: v0.12.12
+  rev: v0.15.7
   hooks:
     # Run the linter.
     - id: ruff-check
-      types_or: [ python, pyi ]
+      types_or: [ python, pyi, pyproject ]
       args: [ --fix ]
     # Run the formatter.
     - id: ruff-format
@@ -14,5 +31,6 @@ repos:
   hooks:
     - id: ty
       name: ty check
-      entry: uvx ty check . --ignore unresolved-import
-      language: python
+      entry: uv run ty check . --ignore unresolved-import
+      language: system
+      pass_filenames: false

CONTRIBUTING.md

@@ -60,11 +60,8 @@ source .venv/bin/activate  # On macOS/Linux
 # OR
 .venv\Scripts\activate     # On Windows
 
-# Install dependencies
+# Install dependencies and the package (dev group is included by default; see tool.uv in pyproject.toml)
 uv sync
-
-# Install package in editable mode
-uv pip install -e .
 ```
 
 **Alternative (if uv is not available):**
@@ -83,13 +80,28 @@ pip install -e .
 ### 3. Install Development Dependencies
 
 ```bash
-# Using uv (recommended)
+# Using uv (recommended): `uv sync` installs the dev group by default
+uv sync
+
+# If you disabled default-groups, install dev explicitly:
 uv sync --group dev
 
-# Using pip
-pip install -e ".[dev]"
+# Using pip: there is no `[project.optional-dependencies]` dev extra; use uv, or install
+# tools from the dev list in pyproject.toml manually after `pip install -e .`
+```
+
+### Git hooks (prek)
+
+After `uv sync`, install hooks so the same checks as CI run on each commit:
+
+```bash
+uv run prek install
+# If you previously used pre-commit and need to replace its hook script:
+uv run prek install -f
 ```
 
+Configuration lives in `.pre-commit-config.yaml` (prek is compatible with this format).
+
 ### 4. Verify Installation
 
 ```bash
@@ -100,7 +112,7 @@ python -m scheduler.main --help
 python -m scheduler.server --help
 
 # Run tests
-pytest
+uv run pytest
 ```
 
 ## Project Structure
@@ -125,10 +137,22 @@ src/scheduler/
 │   └── csv_writer.py       # CSV output writer
 └── time_slot_generator.py  # Time slot generation utilities
 
-docs/                       # Documentation
-├── configuration.md        # Configuration file format
-├── python_api.md           # Python API
-└── rest_api.md             # REST API
+fern/                       # Fern documentation site (published to Fern Cloud)
+├── docs.yml                # Site config, navigation, branding
+├── generators.yml          # OpenAPI spec registration
+├── openapi.json            # Generated from FastAPI (do not edit by hand)
+├── fern.config.json        # Fern org + CLI version
+└── docs/
+    ├── pages/              # MDX guides (configuration, Python, dev, …)
+    └── assets/             # Logos, favicon, combined-config.schema.json
+
+docs/
+└── configuration.md        # Redirect pointer to published docs
+
+scripts/
+├── export_openapi.py       # Refresh fern/openapi.json
+├── export_config_schema.py # Refresh JSON Schema asset
+└── gen_python_api_mdx.py   # Refresh Python API reference from docstrings
 ```
 
 ## Development Workflow
@@ -153,11 +177,17 @@ git checkout -b feature/your-feature-name
 ### 3. Test Your Changes
 
 ```bash
+# Run tests
+uv run pytest
+
 # Run linting
-ruff check
+uv run ruff check .
 
 # Run type checking
-ty check
+uv run ty check . --ignore unresolved-import
+
+# Or run the full hook suite (matches CI)
+uv run prek run --all-files
 ```
 
 ### 4. Commit Your Changes
@@ -223,17 +253,17 @@ from .config import SchedulerConfig
 ```python
 def generate_schedule(config: SchedulerConfig) -> List[CourseInstance]:
     """Generate a course schedule based on configuration.
-    
+
     **Args:**
     - config: The scheduler configuration containing courses, faculty, and constraints.
-    
+
     **Returns:**
     A list of course instances representing the generated schedule.
-    
+
     **Raises:**
     - ValueError: If the configuration is invalid.
     - RuntimeError: If no valid schedule can be generated.
-    
+
     **Example:**
         >>> config = load_config_from_file("config.json")
         >>> schedule = generate_schedule(config, limit=5)
@@ -283,23 +313,25 @@ if not faculty_available:
 - Update REST API documentation for new endpoints
 - Include request/response examples
 - Document error codes and messages
-- Update OpenAPI schema if applicable
+- Regenerate **`fern/openapi.json`** with `uv run python scripts/export_openapi.py` when `server.py` or shared models change
+- Regenerate **`fern/docs/pages/python/reference.mdx`** with `uv run python scripts/gen_python_api_mdx.py` when public docstrings change
 
 ### User Documentation
 
+- Update **Fern** pages under **`fern/docs/pages/`** (configuration, welcome, development)
 - Update README.md for new features
-- Add configuration examples
-- Update troubleshooting guides
-- Include performance considerations
+- Regenerate **`fern/docs/assets/combined-config.schema.json`** with `uv run python scripts/export_config_schema.py` when `CombinedConfig` changes
+- Preview locally: `npm install -g fern-api` then `fern docs dev` (after the generate scripts above)
 
 ## Submitting Changes
 
 ### Pull Request Checklist
 
 Before submitting a pull request, ensure:
 
-- [ ] Code passes linting (`ruff check`)
-- [ ] Type checking passes (`ty check`)
+- [ ] Code passes linting (`uv run ruff check .`)
+- [ ] Type checking passes (`uv run ty check . --ignore unresolved-import`)
+- [ ] Tests pass (`uv run pytest`)
 - [ ] Documentation is updated
 - [ ] Breaking changes are documented
 - [ ] Commit messages follow conventional format

LICENSE

@@ -16,4 +16,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.