diff --git a/.github/scripts/prepare_docs.py b/.github/scripts/prepare_docs.py index 3cb0a2b..7460d48 100644 --- a/.github/scripts/prepare_docs.py +++ b/.github/scripts/prepare_docs.py @@ -3,7 +3,7 @@ import glob import re import shutil -folders_to_copy = ["src", "scripts"] +folders_to_copy = ["src", "scripts", "configs" ] for folder in folders_to_copy: if os.path.exists(folder): shutil.copytree(folder, f"docs/{folder}", dirs_exist_ok=True) @@ -12,9 +12,9 @@ for filepath in glob.glob("docs/**/*.md", recursive=True): with open(filepath, "r", encoding="utf-8") as f: content = f.read() - # RULE A: Fix links pointing OUT to src/ or scripts/ + # RULE A: Fix links pointing OUT to src/, scripts/, or configs/ # Logic: Because the folders were moved one level deeper, we remove exactly ONE '../' - content = re.sub(r"\]\(\.\./((?:\.\./)*)(src|scripts)/([^)]*)\)", r"](\1\2/\3)", content) + content = re.sub(r"\]\(\.\./((?:\.\./)*)(src|scripts|configs)/([^)]*)\)", r"](\1\2/\3)", content) # RULE B: Fix links pointing FROM the copied files back TO the original docs/ folder # Logic: Since these files are now inside docs/, the 'docs/' segment in the path is redundant. diff --git a/docs/README.md b/docs/README.md index ec73a8f..c2edd2f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -9,6 +9,7 @@ For the core codebase, scripts, and contribution history, visit our [GitHub Repo - **[Installation Instructions](./DEVELOPMENT.md)**: Steps to set up your development environment locally or in a devcontainer using `uv`, including GPU configuration. For High-Performance Computing (HPC) setup details, see the **[HPC Guide](./HPC.md)**. - **[How to Run Experiments](./api/training.md)**: A complete guide on running training jobs, setting custom hyperparameters, and overriding config options using Hydra. - **[Results & Reproduction](./api/reproduction.md)**: Guide on how to access our public WandB training runs table and reproduce our training and evaluation phases (determining the best checkpoint vs. comparing architectures). +- **[Contribution Guidelines](./CONTRIBUTING.md)**: Standards, rules, and best practices for developing and adding code to the repository. - **[Repository Structure](#repository-structure)**: Overview of the directories and files within the codebase. ## Repository Structure diff --git a/docs/api/evaluation.md b/docs/api/evaluation.md index 45b880e..1828a7f 100644 --- a/docs/api/evaluation.md +++ b/docs/api/evaluation.md @@ -54,3 +54,7 @@ python scripts/evaluate_checkpoints.py \ ``` This script scans the `checkpoints/` directory of the specified run and evaluates every `.flax` file it finds using the model's training morphology. + +--- + +For a step-by-step walkthrough on using these evaluation phases to reproduce our project results, see the **[Results & Reproduction Guide](./reproduction.md)**. diff --git a/docs/api/tracking.md b/docs/api/tracking.md index 00eed22..77178f7 100644 --- a/docs/api/tracking.md +++ b/docs/api/tracking.md @@ -58,3 +58,7 @@ uv run python scripts/analysis/explore_tensorboard.py runs/your_run_name/ ``` See the detailed description in [`/scripts/analysis/README.md`](../../scripts/analysis/README.md). + +## Developer Logging API + +For details on the developer API of our internal logging library (how backend routing, checkpoint synchronization, and singleton initialization works), see the **[Experiment Logger API Guide](../../src/experiment_logger/README.md)**. diff --git a/docs/api/training.md b/docs/api/training.md index 197e76f..b93b910 100644 --- a/docs/api/training.md +++ b/docs/api/training.md @@ -6,6 +6,8 @@ This guide covers how to configure and run training experiments for the Brittle The project uses a modular configuration system powered by [Hydra](https://hydra.cc/). Instead of passing many command-line flags, you select and override configuration groups. +For a detailed guide on the structure, validation, and usage of our Hydra configuration files, see the **[Brittle Star Configuration System Guide](../../configs/README.md)**. + ### Creating a Custom Experiment 1. **Create a new experiment file:**