chore: cleanup PR for review

- Remove brand book file (reference material, not needed in repo)
- Update README with new CLI commands and workflow documentation
- Add inline documentation explaining DevSeed modifications
- Remove commented-out code from index.js
- Add docstrings to config.py

Author: aboydnw

DS-BrandBook_v003-2024.docx

@@ -1,48 +1,134 @@
-# Development Seed contributor network
+# Development Seed Contributor Network
 
 The code behind <https://developmentseed.org/contributor-network>.
 
 ![A splash of the page](./img/site-image.jpg)
 
-This visual is derived from the excellent <https://github.com/nbremer/ORCA/tree/main/top-contributor-network>.
+This visual is derived from the excellent [ORCA top-contributor-network](https://github.com/nbremer/ORCA/tree/main/top-contributor-network) by Nadieh Bremer.
 
-## Rebuilding
+## Quick Start
 
-We use [workflow dispatch](https://github.com/developmentseed/contributor-network/actions/workflows/build.yml) to rebuild the source data.
-Right now this is manual, but eventually we'd like to set this up on a schedule: <https://github.com/developmentseed/contributor-network/issues/8>.
+### Prerequisites
 
-## Development
+- [uv](https://docs.astral.sh/uv/getting-started/installation/) for Python package management
+- A GitHub personal access token with `public_repo` scope
 
-To view things locally:
+### View Locally
 
 ```shell
-python -m http.server
+cd dist
+python -m http.server 8000
 ```
 
-This will open the page on <http://localhost:8000/>.
+Then open <http://localhost:8000/>.
+
+## CLI Commands
+
+All commands are run via `uv run contributor-network <command>`.
+
+### `list-contributors`
 
-To check the Python files, get [uv](https://docs.astral.sh/uv/getting-started/installation/), then:
+List all configured contributors by category:
 
 ```shell
-uv sync
-uv run ruff check --fix
-uv run ruff format
-uv run pytest
+uv run contributor-network list-contributors
 ```
 
-To add new repos or contributors, see [constants.py](src/devseed_contributor_network/constants.py)
+### `discover`
+
+Find new repositories that DevSeed employees contribute to:
 
-### Rebuilding locally
+```shell
+export GITHUB_TOKEN="your_token_here"
+uv run contributor-network discover --min-contributors 2 --limit 50
+```
 
-To build the data locally, set up [.netrc authentication for Github](https://pygithub.readthedocs.io/en/stable/examples/Authentication.html#netrc-authentication).
-Then:
+This queries GitHub to find repos where multiple DevSeed employees have contributed, which are not yet in the configuration.
+
+### `data`
+
+Fetch contribution data from GitHub for all configured repositories:
 
 ```shell
+export GITHUB_TOKEN="your_token_here"
 uv run contributor-network data data
+```
+
+Options:
+- `--all-contributors`: Include alumni/friends (not just current DevSeed employees)
+
+### `csvs`
+
+Generate CSV files from the fetched JSON data:
+
+```shell
 uv run contributor-network csvs data
+```
+
+### `build`
+
+Build the static site to the `dist/` folder:
+
+```shell
 uv run contributor-network build data dist
 ```
 
+## Full Workflow
+
+To update the visualization with new data:
+
+```shell
+# 1. Set your GitHub token
+export GITHUB_TOKEN="your_token_here"
+
+# 2. (Optional) Discover new repos to add
+uv run contributor-network discover --min-contributors 2
+
+# 3. Edit config.toml to add/remove repos or contributors
+
+# 4. Fetch data from GitHub
+uv run contributor-network data data
+
+# 5. Generate CSVs
+uv run contributor-network csvs data
+
+# 6. Build the site
+uv run contributor-network build data dist
+
+# 7. Preview locally
+cd dist && python -m http.server 8000
+```
+
+## Configuration
+
+Edit `config.toml` to configure:
+
+- **repositories**: List of GitHub repos to track (format: `"owner/repo"`)
+- **contributors.devseed**: Current DevSeed employees (format: `github_username = "Display Name"`)
+- **contributors.alumni**: Friends and alumni (commented out by default)
+
+## Development
+
+### Code Quality
+
+```shell
+uv sync
+uv run ruff check --fix
+uv run ruff format
+uv run pytest
+```
+
+### Automated Rebuilds
+
+We use [workflow dispatch](https://github.com/developmentseed/contributor-network/actions/workflows/build.yml) to rebuild the source data manually.
+
+## Branding
+
+This visualization uses the Development Seed brand colors:
+- **Grenadier** (#CF3F02): Primary orange accent
+- **Aquamarine** (#2E86AB): Secondary blue
+- **Base** (#443F3F): Text color
+
 ## License
 
 This work was copied-and-modified from <https://github.com/nbremer/ORCA> and is licensed under the same (MPL).

README.md

@@ -1,7 +1,15 @@
 // This file was copied-and-modified from
 // https://github.com/nbremer/ORCA/blob/77745774d9d189818ab1ba27e07979897434abf9/top-contributor-network/createORCAVisual.js,
 // and is licensed under the same (MPL).
-
+//
+// Development Seed Modifications:
+// - Updated color scheme to DevSeed brand (Grenadier orange, Aquamarine blue)
+// - Removed the central "team" pseudo-node from rendering (but kept for layout)
+// - Added null safety checks for hover/click interactions
+// - Added boundary checking to prevent hover outside visualization area
+// - Added mouseleave handler to properly clean up hover state
+// - Filtered out artificial links to/from the central pseudo-node
+//
 /////////////////////////////////////////////////////////////////////
 /////////////// Visualization designed & developed by ///////////////
 /////////////////////////// Nadieh Bremer ///////////////////////////
@@ -1503,12 +1511,6 @@ const createORCAVisual = (
   } // function drawNode
 
   function drawNodeArc(context, SF, d) {
-    // Skip arc drawing for the central pseudo-node concept since it's been removed
-    // The original showed time involvement with a central repo, but we no longer have one
-    // if (d.type === "contributor" && !CLICK_ACTIVE) {
-    //   timeRangeArc(context, SF, d, central_repo, d.data.link_central);
-    // }
-
     // Draw an arc around the repository node that shows how long the contributor has been active in that repo for all its existence, based on the first and last commit time
     if (
       HOVER_ACTIVE &&

index.js

@@ -1,3 +1,9 @@
+"""Configuration management for the contributor network visualization.
+
+The config supports categorizing contributors into groups (e.g., "devseed" for current
+employees, "alumni" for past contributors). This allows filtering the visualization
+to show only active team members while preserving historical data.
+"""
 from __future__ import annotations
 
 import tomllib
@@ -7,6 +13,18 @@
 
 
 class Config(BaseModel):
+    """Configuration for the contributor network visualization.
+    
+    Attributes:
+        title: Page title for the visualization
+        author: Author attribution
+        description: Description shown on the page
+        central_repository: Label for the central node (e.g., "DevSeed Team")
+        repositories: List of GitHub repos to track (format: "owner/repo")
+        contributors: Nested dict of contributor categories, each mapping
+                      GitHub username to display name
+        contributor_padding: Padding around contributor nodes in pixels
+    """
     title: str
     author: str
     description: str