diff --git a/.claude/skills/review-pr/SKILL.md b/.claude/skills/review-pr/SKILL.md index b614db0..60bf51e 100644 --- a/.claude/skills/review-pr/SKILL.md +++ b/.claude/skills/review-pr/SKILL.md @@ -38,28 +38,33 @@ For every new line added to `README.md`, check the following: #### 5a. Entry format -Each entry MUST match one of these accepted formats: +Each entry MUST include one or more language tags and match one of these accepted formats: -**GitHub project:** +**Single language:** ``` -- [Project Name](https://github.com/owner/repo) - Short description ending with a period. +- [Project Name](https://github.com/owner/repo) - `Python` - Short description ending with a period. +``` + +**Multiple languages:** +``` +- [Project Name](https://github.com/owner/repo) - `Python` `Rust` - Short description ending with a period. ``` **Project with website and GitHub repo:** ``` -- [Project Name](https://project-site.com) - Short description ending with a period. [GitHub](https://github.com/owner/repo) +- [Project Name](https://project-site.com) - `Python` - Short description ending with a period. [GitHub](https://github.com/owner/repo) ``` **CRAN project (with optional GitHub link):** ``` -- [Package Name](https://cran.r-project.org/package=pkgname) - Short description ending with a period. -- [Package Name](https://cran.r-project.org/package=pkgname) - Short description ending with a period. [GitHub](https://github.com/owner/repo) +- [Package Name](https://cran.r-project.org/package=pkgname) - `R` - Short description ending with a period. +- [Package Name](https://cran.r-project.org/package=pkgname) - `R` - Short description ending with a period. [GitHub](https://github.com/owner/repo) ``` **PyPI project (with optional GitHub link):** ``` -- [package-name](https://pypi.org/project/package-name/) - Short description ending with a period. -- [package-name](https://pypi.org/project/package-name/) - Short description ending with a period. [GitHub](https://github.com/owner/repo) +- [package-name](https://pypi.org/project/package-name/) - `Python` - Short description ending with a period. +- [package-name](https://pypi.org/project/package-name/) - `Python` - Short description ending with a period. [GitHub](https://github.com/owner/repo) ``` The core regex used by `parse.py` to extract entries is: `^\s*- \[(.*)\]\((.*)\) - (.*)$` @@ -68,11 +73,12 @@ Specifically check: - Starts with `- ` (dash + space) - Followed by a markdown link `[Name](URL)` - Followed by ` - ` (space, dash, space) +- **MUST include one or more language tags in backticks** (e.g., `` `Python` ``, `` `Python` `Rust` ``) followed by ` - ` - Followed by a description that ends with a period `.` - The period must come before the optional `[GitHub](url)` link - The `[GitHub]` link, if present, must use the exact format `[GitHub](https://github.com/owner/repo)` -If the entry doesn't match, report exactly what's wrong (missing period, wrong separator, etc.). +If the entry doesn't match, report exactly what's wrong (missing language tags, missing period, wrong separator, etc.). #### 5b. URL validation @@ -85,26 +91,34 @@ If the entry doesn't match, report exactly what's wrong (missing period, wrong s #### 5c. Section placement -Look at which `##` (language) and `###` (category) heading the entry was added under. Evaluate whether the project fits that section: +The README is now organized by **category** (not by language). Look at which `##` (category) heading the entry was added under. Evaluate whether the project fits that section: -- Does the project's language match the section? (e.g., a Python library should be under `## Python`) -- Does the project's purpose match the category? (e.g., a backtesting framework should be under `### Trading & Backtesting`, not `### Indicators`) +- Does the project's purpose match the category? (e.g., a backtesting framework should be under `## Trading & Backtesting`, not under `## Technical Indicators`) - Commercial/proprietary projects must go under `## Commercial & Proprietary Services`. - If the placement seems wrong, suggest a better section. -The current sections in the README are: +The current category sections in the README are: -**Python**: Numerical Libraries & Data Structures, Financial Instruments and Pricing, Indicators, Trading & Backtesting, Risk Analysis, Factor Analysis, Sentiment Analysis, Quant Research Environment, Time Series, Calendars, Data Sources, Excel Integration, Visualization +1. Numerical Libraries & Data Structures +2. Financial Instruments & Pricing +3. Technical Indicators +4. Trading & Backtesting +5. Portfolio Optimization & Risk Analysis +6. Factor Analysis +7. Sentiment Analysis & Alternative Data +8. Time Series Analysis +9. Market Data & Data Sources +10. Prediction Markets +11. Calendars & Market Hours +12. Visualization +13. Excel & Spreadsheet Integration +14. Quant Research Environments +15. Cross-Language Frameworks +16. Reproducing Works, Training & Books +17. Commercial & Proprietary Services +18. Related Lists -**R**: Numerical Libraries & Data Structures, Data Sources, Financial Instruments and Pricing, Trading, Backtesting, Risk Analysis, Factor Analysis, Time Series, Calendars - -**Other languages**: Matlab, Julia, Java, JavaScript, Haskell, Scala, Ruby, Elixir/Erlang, Golang, CPP, CSharp, Rust - -**Cross-language**: Frameworks, Reproducing Works Training & Books - -**Commercial & Proprietary Services** - -If the project doesn't fit any existing section, suggest the closest match or recommend creating a new subsection (rare). +If the project doesn't fit any existing section, suggest the closest match or recommend creating a new category section (rare). #### 5d. Duplicate check diff --git a/CLAUDE.md b/CLAUDE.md index 6173e2e..b247830 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## 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 programming language (Python, R, Matlab, Julia, Java, JavaScript, etc.) with categorized links to open-source projects. +**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. @@ -12,9 +12,15 @@ A companion website is generated from this data and deployed to GitHub Pages. The pipeline works as follows: -1. **`README.md`** — The source of truth. All library entries follow the format: `- [name](url) - Description.` -2. **`parse.py`** — Parses `README.md`, extracts GitHub/CRAN/PyPI URLs, fetches last commit dates and stars via the GitHub API (using `PyGithub` with multithreading), and writes `site/projects.csv`. -3. **`site/generate.py`** — Reads `projects.csv` (or parses `README.md` directly) and generates a static HTML site with search, filtering, sorting, and dark mode. +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: @@ -36,17 +42,20 @@ uv run python site/generate.py ## Contributing Entries -See `CONTRIBUTING.md` for full guidelines. Accepted entry formats: +See `CONTRIBUTING.md` for full guidelines. All entries must include language tags: ``` -- [Project Name](https://github.com/owner/repo) - Description ending with a period. -- [Project Name](https://site.com) - Description ending with a period. [GitHub](https://github.com/owner/repo) -- [Package Name](https://cran.r-project.org/package=pkg) - Description ending with a period. -- [package-name](https://pypi.org/project/pkg/) - Description ending with a period. +- [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 language headings (`##`) and category subheadings (`###`). Commercial/proprietary projects go under `## Commercial & Proprietary Services`. +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` relies on this regex to extract entries: `^\s*- \[(.*)\]\((.*)\) - (.*)$` +`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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4fcafe0..3d31489 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,12 +4,20 @@ Your contributions are always welcome! Please ensure your pull request meets the ## Entry Format -Each entry must follow one of these formats: +Each entry must include one or more language tags and follow one of these formats: -### GitHub project +### Single language ```markdown -- [Project Name](https://github.com/owner/repo) - Short description ending with a period. +- [Project Name](https://github.com/owner/repo) - `Python` - Short description ending with a period. +``` + +### Multiple languages + +For projects available in multiple languages, list them as backtick-delimited tags: + +```markdown +- [Project Name](https://github.com/owner/repo) - `Python` `Rust` - Short description ending with a period. ``` ### Project with website and GitHub repo @@ -17,7 +25,7 @@ Each entry must follow one of these formats: For projects that have a dedicated website, link to the site and append the GitHub repo in the description: ```markdown -- [Project Name](https://project-site.com) - Short description ending with a period. [GitHub](https://github.com/owner/repo) +- [Project Name](https://project-site.com) - `Python` - Short description ending with a period. [GitHub](https://github.com/owner/repo) ``` ### CRAN project @@ -25,8 +33,8 @@ For projects that have a dedicated website, link to the site and append the GitH Link to the CRAN package page. If the project has a GitHub repo, append it after the description: ```markdown -- [Package Name](https://cran.r-project.org/package=pkgname) - Short description ending with a period. -- [Package Name](https://cran.r-project.org/package=pkgname) - Short description ending with a period. [GitHub](https://github.com/owner/repo) +- [Package Name](https://cran.r-project.org/package=pkgname) - `R` - Short description ending with a period. +- [Package Name](https://cran.r-project.org/package=pkgname) - `R` - Short description ending with a period. [GitHub](https://github.com/owner/repo) ``` ### PyPI project @@ -34,8 +42,8 @@ Link to the CRAN package page. If the project has a GitHub repo, append it after Link to the PyPI package page. If the project has a GitHub repo, append it after the description: ```markdown -- [package-name](https://pypi.org/project/package-name/) - Short description ending with a period. -- [package-name](https://pypi.org/project/package-name/) - Short description ending with a period. [GitHub](https://github.com/owner/repo) +- [package-name](https://pypi.org/project/package-name/) - `Python` - Short description ending with a period. +- [package-name](https://pypi.org/project/package-name/) - `Python` - Short description ending with a period. [GitHub](https://github.com/owner/repo) ``` ### General rules @@ -57,7 +65,28 @@ Commercial and proprietary projects are welcome. They will be placed under the * ## Section Placement -Add your entry under the correct language heading (`##`) and category subheading (`###`). If the project is a Python backtesting library, it goes under `## Python` → `### Trading & Backtesting`, not under `### Indicators`. +The README is organized by **category** (not by language). Add your entry under the appropriate category heading (`##`). The available categories are: + +- Numerical Libraries & Data Structures +- Financial Instruments & Pricing +- Technical Indicators +- Trading & Backtesting +- Portfolio Optimization & Risk Analysis +- Factor Analysis +- Sentiment Analysis & Alternative Data +- Time Series Analysis +- Market Data & Data Sources +- Prediction Markets +- Calendars & Market Hours +- Visualization +- Excel & Spreadsheet Integration +- Quant Research Environments +- Cross-Language Frameworks +- Reproducing Works, Training & Books +- Commercial & Proprietary Services +- Related Lists + +For example, if your project is a Python backtesting library, it goes under `## Trading & Backtesting` (not under Technical Indicators or another category). If no existing category fits, suggest a new one in your PR description.