Skip to content

Commit fbfd5fb

Browse files
Magic-Man-usMagic-Man-us
committed
fix: add --all-extras to sphinx-build and use furo theme
- Fixed sphinx-build not installing docs dependencies - Changed from sphinx-rtd-theme to furo in pyproject template - Ensures documentation builds successfully during scaffolding
1 parent c6b74f5 commit fbfd5fb

File tree

11 files changed

+455
-2
lines changed

11 files changed

+455
-2
lines changed

‎.clinerules/00-critical.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Critical Directives
2+
3+
These rules must be followed without exception.
4+
5+
## Package Management
6+
ONLY USE UV, NO PIP ALLOWED.
7+
8+
## Version Control
9+
DO NOT RESTORE FILES VIA GIT.
10+
11+
## Primary Language
12+
Python is the primary language. All standards apply universally.
13+
14+
## Enforcement
15+
All standards must be adhered to strictly to maintain code quality and consistency across the project, focused on Python best practices, PEP 8 compliance, and clarity, maintainability, testability.

‎.clinerules/01-project-structure.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# Project Structure
2+
3+
**CRITICAL:** Verify file tree structure matches the standard layout before starting any work.
4+
5+
## Standard Directory Layout
6+
7+
Replace `{package_name}` with the actual package name.
8+
9+
```
10+
project_root/
11+
│
12+
├── .github/
13+
│ └── workflows/
14+
│ └── ci.yml
15+
│
16+
├── src/
17+
│ └── {package_name}/
18+
│ ├── __init__.py
19+
│ ├── main.py
20+
│ ├── utils/
21+
│ └── logger/
22+
│ └── logger.py
23+
│
24+
├── data/
25+
├── tests/
26+
│ ├── conftest.py
27+
│ ├── unit/
28+
│ └── integration/
29+
│
30+
├── docs/
31+
├── logs/
32+
├── scripts/
33+
├── requirements.txt
34+
├── Makefile
35+
├── README.md
36+
├── LICENSE
37+
├── .gitignore
38+
├── CONTRIBUTING.md
39+
├── SECURITY.md
40+
├── uv.lock
41+
├── .env
42+
└── pyproject.toml
43+
```
44+
45+
## Directory Roles
46+
47+
| Path | Purpose |
48+
|------|---------|
49+
| `.github/workflows/` | CI/CD pipeline definitions |
50+
| `src/{package_name}/` | Application source code |
51+
| `src/{package_name}/main.py` | Entry point |
52+
| `src/{package_name}/utils/` | Helper functions |
53+
| `src/{package_name}/logger/` | Logging setup |
54+
| `data/` | Raw data files |
55+
| `tests/unit/` | Unit tests |
56+
| `tests/integration/` | Integration tests |
57+
| `tests/conftest.py` | Test fixtures |
58+
| `docs/` | Documentation |
59+
| `logs/` | Runtime logs |
60+
| `scripts/` | Automation scripts |
61+
| `requirements.txt` | Dependencies |
62+
| `uv.lock` | UV lock file |
63+
| `.env` | Environment variables |
64+
| `Makefile` | Build commands |
65+
66+
## Required Files
67+
68+
- `__init__.py` in all package directories
69+
- `conftest.py` for pytest fixtures
70+
- `README.md`, `LICENSE`, `CONTRIBUTING.md`, `SECURITY.md`
71+
- `.gitignore`, `.env`
72+
- `Makefile` with UV commands
73+
- `pyproject.toml`
74+
75+
## Verification
76+
77+
Before creating new features or refactoring:
78+
1. Run `tree` command in project root
79+
2. Compare against standard layout
80+
3. Clean up old files/directories no longer needed
81+
4. Check for duplicate files before creating new ones

‎.clinerules/02-coding-standards.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Python Coding Standards
2+
3+
## PEP 8 Compliance
4+
- Follow PEP 8 guidelines strictly
5+
- Max line length: 100 characters
6+
- Proper indentation and spacing
7+
8+
## Naming Conventions
9+
- `snake_case` for functions and variables
10+
- `PascalCase` for classes
11+
- `UPPER_SNAKE_CASE` for constants
12+
13+
## Imports
14+
Group in order, separated by blank lines:
15+
1. Standard library
16+
2. Third-party packages
17+
3. Local application imports
18+
19+
## Type Hints
20+
Use type hints for all function signatures to improve readability and enable static analysis.
21+
22+
## String Formatting
23+
- Use f-strings when no user input is involved
24+
- Use `.format()` method when user input is present (security)
25+
26+
## Data Structures
27+
- Use Pydantic models for external data boundaries (API, database, user input)
28+
- Use standard dataclasses for internal structures
29+
- Prefer `frozen=True` for immutability
30+
31+
## Error Handling
32+
- Implement structured logging throughout
33+
- Never log sensitive information
34+
- Use appropriate exception types
35+
36+
## Code Organization
37+
- Avoid deep nesting (max 3-4 levels)
38+
- Keep functions focused and single-purpose
39+
- Extract complex logic into helper functions

‎.clinerules/03-testing.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Testing Standards
2+
3+
## Test Structure
4+
- Unit tests in `tests/unit/`
5+
- Integration tests in `tests/integration/`
6+
- Shared fixtures in `tests/conftest.py` (CENTRAL LOCATION - DO NOT DUPLICATE)
7+
8+
## Test Guidelines
9+
- Mock external dependencies
10+
- Keep tests focused, deterministic, and fast
11+
- Cover main paths and exception handling
12+
- Use hypothesis for property-based tests when valuable
13+
- Integration tests cover edge cases
14+
15+
## Fixture Management
16+
- Use `tests/conftest.py` as the CENTRAL fixture location
17+
- DO NOT duplicate fixtures across test files
18+
- Define shared fixtures once in conftest.py
19+
- Use fixture scopes appropriately (function, class, module, session)
20+
21+
## Test Organization
22+
- Name test files with `test_` prefix
23+
- Name test functions with `test_` prefix
24+
- Group related tests in classes when appropriate
25+
- Keep test functions small and focused

‎.clinerules/04-documentation.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Documentation Standards
2+
3+
## Docstrings
4+
- Required for all public classes, methods, and functions
5+
- Include: purpose, parameters, return values, exceptions
6+
- Follow Sphinx/Google style consistently
7+
8+
## Comments
9+
10+
### Brief Overview
11+
These rules govern code comments and documentation standards. Focus is on keeping code clean and avoiding unhelpful or redundant comments.
12+
13+
### Comment Guidelines
14+
15+
- **Keep helpful TODOs**: Preserve actionable TODO comments that clearly indicate work needed
16+
- Example: `# TODO: Implement via market data adapter`
17+
- Example: `# TODO: Add get_recent_trade_outcomes method to transaction service`
18+
19+
- **Remove historical/context comments**: Delete comments that explain where code came from or past refactoring history
20+
- ❌ BAD: `(merged from agent/portfolio.py)`
21+
- ❌ BAD: `NOTE: This function was previously in utils/old_file.py`
22+
- ❌ BAD: `This method has been refactored to remove direct SQLite access`
23+
24+
- **No explanatory NOTE comments**: Do not add NOTE comments during refactoring that merely state what was done
25+
- ❌ BAD: `NOTE: This function requires market data adapter that provides historical bars. It no longer uses direct database access.`
26+
- ✅ GOOD: Keep the docstring simple and focused on current behavior
27+
28+
- **Docstrings should be current**: Focus on what the function does NOW, not what it used to do or how it changed
29+
- ✅ GOOD: "Calculate pairwise correlation between all symbols."
30+
- ❌ BAD: "Calculate pairwise correlation between all symbols. NOTE: This function has been refactored..."
31+
32+
### Code Cleanliness
33+
34+
- Code should be self-documenting where possible
35+
- Comments that don't add value should be removed
36+
- Historical context belongs in git history, not in code comments
37+
- If a comment doesn't help someone using or maintaining the code, it shouldn't be there
38+
39+
### Basic Standards
40+
41+
- Place above code, not beside (except brief end-of-line comments)
42+
- Avoid obvious statements
43+
- Start with capital letter, end with period
44+
- Update when code changes
45+
46+
## Markdown Files
47+
- Professional senior dev tone
48+
- Clear, concise, direct
49+
- No fluff or filler words
50+
- Proper syntax and formatting
51+
- No third-person references
52+
53+
## Documentation Tasks
54+
- Create ModelContextProtocol for accessing code indices
55+
- Structure documentation with clear sections and headings
56+
- Enable quick reference and navigation
57+
- Provide clear explanations of functionality, purpose, and usage

‎.clinerules/05-dependencies.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Dependency Management
2+
3+
## Package Manager
4+
ONLY USE UV for dependency management. DO NOT USE pip or conda.
5+
6+
## Standard Package Requirements
7+
8+
### Core Data & Validation
9+
- `pydantic` - ALL data validation, serialization, JSON encoding/decoding, data models
10+
- `pydantic_settings` - Configuration and environment management
11+
- `pydantic_ai` - AI-related data models and validation
12+
13+
### Testing
14+
- `pytest` - Test framework
15+
- `pytest-mock` - Mocking support
16+
17+
### Standard Library Usage
18+
- `asyncio` - Asynchronous programming
19+
- `logging` - Application logging
20+
- `datetime.datetime` - Date/time operations
21+
- `typing` - Type hints and annotations
22+
- `pathlib` - Filesystem paths
23+
- `contextlib` - Context managers
24+
- `collections` - Specialized containers
25+
- `functools` - Higher-order functions
26+
- `itertools` - Iterator building blocks
27+
28+
### Additional Tools
29+
- `sphinx` - Documentation generation
30+
- `uv` - Dependency management (ONLY)
31+
- `click` - CLI development
32+
- `sqlalchemy` - Database interactions
33+
34+
## UV Workflow
35+
36+
Use Makefile targets for common tasks:
37+
- `make install` - Install dependencies
38+
- `make update` - Update dependencies
39+
- `make docs` - Build Sphinx documentation
40+
- `make precommit` - Install pre-commit hooks
41+
- `make clean` - Remove build artifacts
42+
- `make lock` - Create the uv.lock file
43+
44+
If no Makefile exists, create one with these commands following the existing structure and conventions.

‎.clinerules/06-mcp-tools.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# MCP Server Usage
2+
3+
## Primary Tool for Documentation Access
4+
Use the MCP server for AI Documentation Access as your primary tool for accessing project documentation. This tool allows you to query the project's documentation in real-time, providing accurate and up-to-date information about the codebase.
5+
6+
## MCP Server Capabilities
7+
8+
### Search and Reference
9+
- Search docstrings and API documentation
10+
- Understand current codebase structure
11+
- Reference exact function signatures and type hints
12+
- Quote documentation verbatim
13+
- Provide context-aware suggestions based on established patterns
14+
15+
### Features
16+
- **Local-first**: Works offline, all data stays on your machine
17+
- **Fast BM25 search**: Sub-millisecond query times
18+
- **Auto-sync**: Rebuilds docs on every commit via pre-commit hooks
19+
- **Complete coverage**: Extracts all docstrings, type hints, and examples
20+
21+
## Documentation Index Tags
22+
23+
The server indexes the following metadata for fast retrieval:
24+
25+
| Tag | Description |
26+
|-----|-------------|
27+
| `purpose` | Module, class, or function intent |
28+
| `models` | Pydantic models, dataclasses, typed structures |
29+
| `methods` | Class methods and their roles |
30+
| `classes` | Class definitions and inheritance |
31+
| `modules` | Module structure and imports |
32+
| `functions` | Function definitions and usage |
33+
| `signatures` | Parameters, return types, type annotations |
34+
| `exceptions` | Raised exceptions and error conditions |
35+
| `behaviors` | Side effects, branches, conditions |
36+
| `dependencies` | External libraries and internal imports |
37+
38+
## Usage Guidelines
39+
40+
- Query the MCP server when implementing new features
41+
- Use documentation index tags to refine searches
42+
- Reference MCP server to ensure code aligns with established patterns
43+
- Use pydantic-docs MCP when working with Pydantic models
44+
- Always leverage the MCP server for current project standards

0 commit comments

Comments
 (0)