mirror of
https://github.com/wilsonfreitas/awesome-quant.git
synced 2026-08-01 06:17:45 +00:00
Wilson Freitas
c9557e7fd0
CONTRIBUTING.md: - New entry format requires inline language tags (`Python`, `Rust`, etc.) - Updated section placement to list new category sections CLAUDE.md: - Updated architecture: README organized by category, not language - Entry format includes inline language tags - parse.py and site/generate.py extract languages from backtick tags review-pr skill: - Step 5a: validate that entries include required language tags - Step 5c: updated section list to new category-first organization
62 lines
3.2 KiB
Markdown
62 lines
3.2 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
**awesome-quant** is a curated list of quantitative finance libraries, packages, and resources. The primary content lives in `README.md` — a large markdown file **organized by category** (Numerical Libraries, Trading & Backtesting, Market Data, etc.) with inline language tags that identify which programming languages each project supports.
|
|
|
|
A companion website is generated from this data and deployed to GitHub Pages.
|
|
|
|
## Architecture
|
|
|
|
The pipeline works as follows:
|
|
|
|
1. **`README.md`** — The source of truth. All library entries follow the format: `- [name](url) - \`Language\` - Description.`
|
|
- Entries are grouped under category headings (`##`), not language headings
|
|
- Language is identified via inline backtick tags (e.g., `` `Python` ``, `` `Rust` ``) in the description
|
|
- Multi-language projects have multiple tags (e.g., `` `Python` `Rust` ``)
|
|
|
|
2. **`parse.py`** — Parses `README.md`, extracts language from backtick tags, fetches last commit dates and stars via the GitHub API (using `PyGithub` with multithreading), and writes `site/projects.csv` with a `languages` column (comma-separated).
|
|
|
|
3. **`site/generate.py`** — Reads `projects.csv` (or parses `README.md` directly) and generates a static HTML site with search, filtering by language/category/source, sorting, and dark mode.
|
|
|
|
4. **CI** (`.github/workflows/build.yml`) — Runs daily and on push to `main`: runs `parse.py`, runs `site/generate.py`, and deploys to GitHub Pages via `gh-pages` branch.
|
|
|
|
Supporting scripts:
|
|
- `cranscrape.py` — Scrapes CRAN package pages to find associated GitHub repos; writes `cran.csv`.
|
|
- `topic.py` — Searches GitHub for repos tagged with a topic (e.g., "quant") above a star threshold.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
# Install dependencies (uses uv, requires Python 3.11+)
|
|
uv sync --no-install-project
|
|
|
|
# Run the parser (requires GITHUB_ACCESS_TOKEN env var)
|
|
GITHUB_ACCESS_TOKEN=<token> uv run python parse.py
|
|
|
|
# Generate the static site
|
|
uv run python site/generate.py
|
|
```
|
|
|
|
## Contributing Entries
|
|
|
|
See `CONTRIBUTING.md` for full guidelines. All entries must include language tags:
|
|
|
|
```
|
|
- [Project Name](https://github.com/owner/repo) - `Python` - Description ending with a period.
|
|
- [Project Name](https://github.com/owner/repo) - `Python` `Rust` - Multi-language project description.
|
|
- [Project Name](https://site.com) - `Python` - Description ending with a period. [GitHub](https://github.com/owner/repo)
|
|
- [Package Name](https://cran.r-project.org/package=pkg) - `R` - Description ending with a period.
|
|
- [package-name](https://pypi.org/project/pkg/) - `Python` - Description ending with a period.
|
|
```
|
|
|
|
CRAN and PyPI entries may optionally append `[GitHub](url)` after the description.
|
|
|
|
Entries are grouped under category headings (`##`), not language headings. Language is identified via inline backtick tags. Commercial/proprietary projects go under `## Commercial & Proprietary Services`.
|
|
|
|
`parse.py` and `site/generate.py` rely on this regex to extract entries: `^\s*- \[(.*)\]\((.*)\) - (.*)$`
|
|
|
|
The description text (group 3) may start with language tags in the format `` `Language1` `Language2` - `` followed by the actual description.
|