gavindiaz/awesome-quant
1
0
Fork 0
mirror of https://github.com/wilsonfreitas/awesome-quant.git synced 2026-08-21 07:48:05 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update docs for category-first README organization

Browse Source 
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
This commit is contained in:
Wilson Freitas
2026-03-28 11:14:49 -03:00
parent 010d0b4782
commit c9557e7fd0
3 changed files with 95 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude/skills/review-pr/SKILL.md
+37 -23
View File
@@ -38,28 +38,33 @@ For every new line added to `README.md`, check the following:
#### 5a. Entry format #### 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 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):** **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) - `R` - 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. [GitHub](https://github.com/owner/repo)
``` ```
**PyPI project (with optional GitHub link):** **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/) - `Python` - 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. [GitHub](https://github.com/owner/repo)
``` ```
The core regex used by `parse.py` to extract entries is: `^\s*- \[(.*)\]\((.*)\) - (.*)$` The core regex used by `parse.py` to extract entries is: `^\s*- \[(.*)\]\((.*)\) - (.*)$`
@@ -68,11 +73,12 @@ Specifically check:
- Starts with `- ` (dash + space) - Starts with `- ` (dash + space)
- Followed by a markdown link `[Name](URL)` - Followed by a markdown link `[Name](URL)`
- Followed by ` - ` (space, dash, space) - 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 `.` - Followed by a description that ends with a period `.`
- The period must come before the optional `[GitHub](url)` link - 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)` - 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 #### 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 #### 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 under `## Technical Indicators`)
- Does the project's purpose match the category? (e.g., a backtesting framework should be under `### Trading & Backtesting`, not `### Indicators`)
- Commercial/proprietary projects must go under `## Commercial & Proprietary Services`. - Commercial/proprietary projects must go under `## Commercial & Proprietary Services`.
- If the placement seems wrong, suggest a better section. - 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 If the project doesn't fit any existing section, suggest the closest match or recommend creating a new category section (rare).
**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).
#### 5d. Duplicate check #### 5d. Duplicate check
CLAUDE.md
+20 -11
View File
@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
## Project Overview ## 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. 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: The pipeline works as follows:
1. **`README.md`** — The source of truth. All library entries follow the format: `- [name](url) - Description.` 1. **`README.md`** — The source of truth. All library entries follow the format: `- [name](url) - \`Language\` - 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`. - Entries are grouped under category headings (`##`), not language headings
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. - 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. 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: Supporting scripts:
@@ -36,17 +42,20 @@ uv run python site/generate.py
## Contributing Entries ## 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://github.com/owner/repo) - `Python` - Description ending with a period.
- [Project Name](https://site.com) - Description ending with a period. [GitHub](https://github.com/owner/repo) - [Project Name](https://github.com/owner/repo) - `Python` `Rust` - Multi-language project description.
- [Package Name](https://cran.r-project.org/package=pkg) - Description ending with a period. - [Project Name](https://site.com) - `Python` - Description ending with a period. [GitHub](https://github.com/owner/repo)
- [package-name](https://pypi.org/project/pkg/) - Description ending with a period. - [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. 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.
CONTRIBUTING.md
+38 -9
View File
@@ -4,12 +4,20 @@ Your contributions are always welcome! Please ensure your pull request meets the
## Entry Format ## 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 ```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 ### 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: For projects that have a dedicated website, link to the site and append the GitHub repo in the description:
```markdown ```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 ### 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: Link to the CRAN package page. If the project has a GitHub repo, append it after the description:
```markdown ```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) - `R` - 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. [GitHub](https://github.com/owner/repo)
``` ```
### PyPI project ### 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: Link to the PyPI package page. If the project has a GitHub repo, append it after the description:
```markdown ```markdown
- [package-name](https://pypi.org/project/package-name/) - Short description ending with a period. - [package-name](https://pypi.org/project/package-name/) - `Python` - 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. [GitHub](https://github.com/owner/repo)
``` ```
### General rules ### General rules
@@ -57,7 +65,28 @@ Commercial and proprietary projects are welcome. They will be placed under the *
## Section Placement ## 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. If no existing category fits, suggest a new one in your PR description.