From 0778c3cf6f847f89f4b88c7d2ebf47cf60645907 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 3 Feb 2026 13:22:49 +0000 Subject: [PATCH 1/5] Add CLAUDE.md for AI assistant guidance Create comprehensive documentation for AI assistants working with the pyRevit codebase, including project overview, build commands, testing, architecture, and development workflow. https://claude.ai/code/session_01L5v3q2mHBZhdz3CKPgrUfu --- CLAUDE.md | 153 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 153 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000000..888a0884a6 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,153 @@ +# CLAUDE.md + +This file provides guidance for AI assistants working with the pyRevit codebase. + +## Project Overview + +pyRevit is a Rapid Application Development (RAD) environment for Autodesk Revit. It allows users to create automation tools and add-ins using Python (IronPython 2.7.12 default, CPython 3.12.3, or IronPython 3.4.0), C#, or VB.NET. The project includes a CLI utility for deployment and a telemetry server for usage tracking. + +## Repository Structure + +- `bin/` - Pre-built binaries (DLLs) and Python engines (IPY2712PR, IPY342, CPY3123) +- `dev/` - C# source code, build scripts, and solution files +- `docs/` - Documentation source for the website (mkdocs) +- `extensions/` - pyRevit extensions (tools visible in Revit ribbon) +- `extras/` - Additional resources (icons, dark mode generator) +- `licenses/` - Third-party library licenses +- `pyrevitlib/` - Python libraries for Revit API development +- `release/` - Build artifacts and installer configurations +- `site-packages/` - Third-party Python packages (must be IronPython 2.7.12 compatible) + +## Languages and Technologies + +- **Python**: IronPython 2.7.12 (default), CPython 3.12.3, IronPython 3.4.0 +- **C#**: .NET Framework 4.8 (Revit 2017-2024), .NET 8.0 (Revit 2025+) +- **Go**: Telemetry server (`dev/pyRevitTelemetryServer/`) +- **Build Tools**: Visual Studio 2022, pipenv, MSBuild, Inno Setup + +## Build Commands + +All build commands use pipenv. Run from the repository root: + +```bash +# Setup environment +pipenv install +pipenv run pyrevit check # Verify build environment + +# Build commands +pipenv run pyrevit build products # Build all C# DLLs (Release mode) +pipenv run pyrevit build products Debug # Build in Debug mode +pipenv run pyrevit build labs # Build main project only +pipenv run pyrevit build engines # Build Python engines +pipenv run pyrevit build installers # Create Inno Setup installers +pipenv run pyrevit build telem # Build telemetry server + +# Cleaning +pipenv run pyrevit clean labs # Clean build artifacts + +# Version management +pipenv run pyrevit set version # Set version number +pipenv run pyrevit set build wip # Set as work-in-progress +pipenv run pyrevit set build release # Set as release build +``` + +## Documentation Commands + +```bash +pipenv run docs # Build documentation (mkdocs) +pipenv run check-docstrings # Lint docstrings with ruff +``` + +## Testing + +```bash +# Test telemetry server (requires Docker) +pipenv run pyrevit test telem + +# Python unit tests are in pyrevitlib/pyrevit/unittests/ +# C# unit tests are in dev/pyRevitLabs/pyRevitLabs.UnitTests/ +``` + +To test in Revit: +```bash +pyrevit clones add dev +pyrevit attach dev default --installed +``` + +## Development Workflow + +1. Fork and clone the repository +2. Checkout `develop` branch (active development) +3. Initialize submodules: `git submodule update --init --recursive` +4. Install dependencies: `pipenv install` +5. Build: `pipenv run pyrevit build products Debug` +6. Test in Revit by attaching the clone + +For debugging C# code: +1. Build in Debug mode +2. Open the appropriate `.sln` file in Visual Studio +3. Attach debugger to `revit.exe` process + +## Architecture Overview + +### Loading Sequence +1. Revit reads `.addin` manifest from Addins folder +2. Manifest points to `pyRevitLoader.dll` (C#) +3. Loader launches `pyrevitloader.py` in IronPython +4. Python script calls `pyrevit.loader.sessionmgr.load_session()` +5. Extensions are discovered and UI is built + +### Key Components +- **pyRevitLoader** (`dev/pyRevitLoader/`): Revit add-in entry point +- **PyRevit.Runtime** (`dev/pyRevitLabs/pyRevitLabs.PyRevit.Runtime/`): Command execution +- **pyrevitlib** (`pyrevitlib/pyrevit/`): Python API for scripts +- **CLI** (`dev/pyRevitLabs/pyRevitLabs.PyRevit/`): Command-line management + +### Script Engines +Located in `dev/pyRevitLabs/pyRevitLabs.PyRevit.Runtime/`: +- `IronPythonEngine.cs` - Default Python engine +- `CPythonEngine.cs` - Modern Python (3.12) +- `CLREngine.cs` - C#/VB.NET execution +- `DynamoBIMEngine.cs` - Dynamo graphs +- `GrasshopperEngine.cs` - Grasshopper definitions + +## Extension Bundle Structure + +Extensions follow this hierarchy: +``` +MyExtension.extension/ + MyTab.tab/ + MyPanel.panel/ + MyButton.pushbutton/ + bundle.yaml # Button configuration + script.py # Python script + icon.png # Button icon +``` + +Supported bundle types: pushbutton, smartbutton, pulldown, splitbutton, panelbutton + +## Key Configuration Files + +- `Pipfile` - Python dependencies (requires Python 3.10) +- `pyRevitfile` - Engine definitions and deployment profiles +- `pyproject.toml` - Ruff linting config (Google docstring convention) +- `mkdocs.yml` - Documentation generation +- `.gitmodules` - Git submodules for dependencies + +## Code Style + +- Python: Google docstring convention, formatted with black, linted with ruff +- C#: Standard .NET conventions + +## Supported Revit Versions + +2017-2027, with separate builds per version: +- Revit 2017-2024: .NET Framework 4.7.2/4.8 +- Revit 2025+: .NET 8.0 + +## Git Workflow + +- `master` branch: Releases only +- `develop` branch: Active development +- Feature branches from `develop`, PRs back to `develop` +- Run `git submodule update` after switching branches From cce42be155f00da51ba9a7f119373e330633ab53 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 3 Feb 2026 13:54:34 +0000 Subject: [PATCH 2/5] Clarify branch structure in CLAUDE.md Add docs branch for documentation website and note that develop is the main WIP branch. https://claude.ai/code/session_01L5v3q2mHBZhdz3CKPgrUfu --- CLAUDE.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 888a0884a6..921555136b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -148,6 +148,7 @@ Supported bundle types: pushbutton, smartbutton, pulldown, splitbutton, panelbut ## Git Workflow - `master` branch: Releases only -- `develop` branch: Active development +- `develop` branch: Active development (main WIP branch) +- `docs` branch: Documentation website - Feature branches from `develop`, PRs back to `develop` - Run `git submodule update` after switching branches From d4bc1f7db3ce4f62e2020b31b5f5b2c714d541bf Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 3 Feb 2026 13:54:59 +0000 Subject: [PATCH 3/5] Emphasize develop as starting branch in CLAUDE.md Reorder branches to put develop first and clarify that all work should start from develop. Master is for release material only. https://claude.ai/code/session_01L5v3q2mHBZhdz3CKPgrUfu --- CLAUDE.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 921555136b..e33d0c7bed 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -147,8 +147,8 @@ Supported bundle types: pushbutton, smartbutton, pulldown, splitbutton, panelbut ## Git Workflow -- `master` branch: Releases only -- `develop` branch: Active development (main WIP branch) +- `develop` branch: Active development (always start here) +- `master` branch: Release material only - `docs` branch: Documentation website - Feature branches from `develop`, PRs back to `develop` - Run `git submodule update` after switching branches From 2b91a855f4f1b38ad93e9b3512230d3acf97158c Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 3 Feb 2026 13:57:40 +0000 Subject: [PATCH 4/5] Add documentation website URL to CLAUDE.md Link to https://docs.pyrevitlabs.io/ as the main documentation source. https://claude.ai/code/session_01L5v3q2mHBZhdz3CKPgrUfu --- CLAUDE.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index e33d0c7bed..b194290532 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -51,7 +51,9 @@ pipenv run pyrevit set build wip # Set as work-in-progress pipenv run pyrevit set build release # Set as release build ``` -## Documentation Commands +## Documentation + +Main documentation: https://docs.pyrevitlabs.io/ (built from `docs/` folder) ```bash pipenv run docs # Build documentation (mkdocs) From b4d13766b48a9332a631c5c5cdcdacaaf3b45b5c Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 3 Feb 2026 13:59:58 +0000 Subject: [PATCH 5/5] Distinguish main website from technical docs in CLAUDE.md - pyrevitlabs.io is the central website - docs.pyrevitlabs.io is the mkdocs technical documentation https://claude.ai/code/session_01L5v3q2mHBZhdz3CKPgrUfu --- CLAUDE.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index b194290532..8d91ea2b61 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -53,7 +53,8 @@ pipenv run pyrevit set build release # Set as release build ## Documentation -Main documentation: https://docs.pyrevitlabs.io/ (built from `docs/` folder) +- Main website: https://pyrevitlabs.io/ +- Technical docs: https://docs.pyrevitlabs.io/ (mkdocs, built from `docs/` folder) ```bash pipenv run docs # Build documentation (mkdocs)