From 6242519d37e605d87431d6a93a9e2645dc563215 Mon Sep 17 00:00:00 2001 From: Wisaroot Lertthaweedech Date: Wed, 17 Sep 2025 08:45:35 +0700 Subject: [PATCH 1/4] docs: improve docs --- CONTRIBUTING.md | 44 +++++------ README.md | 7 +- docs/cli-usage.md | 5 +- docs/improvement-checklist.md | 133 ++++++++++++++++++++++++++++++++++ 4 files changed, 162 insertions(+), 27 deletions(-) create mode 100644 docs/improvement-checklist.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f1d27ba..d990e98 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,26 +6,34 @@ Thank you for your interest in contributing! This repository welcomes contributi ### 1. Add New Problems -Use an LLM assistant (Cursor, GitHub Copilot Chat, Amazon Q) with the rule files: +For adding new LeetCode problems, please refer to the comprehensive guide: -- Include `.amazonq/rules/problem-creation.md` in your LLM context -- Ask: "Create LeetCode problem [number] ([name])" +๐Ÿ“– **[LLM-Assisted Problem Creation Guide](docs/llm-assisted-problem-creation.md)** -### 2. Enhance Test Cases +This document provides detailed instructions for using LLM assistants to generate new problems with proper templates, test cases, and documentation. -- Include `.amazonq/rules/test-quality-assurance.md` in your LLM context -- Ask: "Enhance test cases for [problem_name] problem" +**Acceptance Criteria:** -### 3. Improve Helper Classes +- All GitHub Actions CI checks must pass (includes linting, testing, security scanning, reproducibility verification, and minimum 10 test cases per problem) +- Proper type hints and code formatting +- Complete the solution (documentation is auto-generated) -- Add new data structure helpers in `leetcode_py/data_structures/` -- Follow existing patterns with generic types and visualization support +### 2. Other Contributions -### 4. Bug Fixes & Improvements +All other contributions are welcome! This includes: -- Fix issues in existing problems -- Improve documentation -- Enhance CI/CD workflows +- Bug fixes and improvements +- Documentation enhancements +- Helper class improvements +- CI/CD workflow enhancements +- Test case enhancements +- New data structure visualizations + +**For small changes:** Feel free to open a pull request directly. + +**For larger changes:** Please open an issue for discussion first. + +I'm also open to feedback and suggestions for improving the project! ## Development Setup @@ -36,20 +44,14 @@ poetry install make test ``` -## Code Standards - -- Follow [PEP 8](https://peps.python.org/pep-0008/) Python style guide -- Use modern type hints per [PEP 585](https://peps.python.org/pep-0585/)/[PEP 604](https://peps.python.org/pep-0604/): `list[str]`, `dict[str, int]`, `Type | None` -- Automated linting enforced by CI (black, isort, ruff, mypy) -- Minimum 12 test cases per problem - ## Pull Request Process 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Run `make lint` and `make test` -5. Submit a pull request with clear description +5. Ensure all GitHub Actions CI checks pass +6. Submit a pull request with clear description ## Questions? diff --git a/README.md b/README.md index d64ae6f..38e11f6 100644 --- a/README.md +++ b/README.md @@ -6,22 +6,25 @@ [![codecov](https://codecov.io/gh/wisarootl/leetcode-py/graph/badge.svg?token=TI97VUIA4Z)](https://codecov.io/gh/wisarootl/leetcode-py) [![tests](https://img.shields.io/github/actions/workflow/status/wisarootl/leetcode-py/ci-test.yml?branch=main&label=tests&logo=github)](https://github.com/wisarootl/zerv/actions/workflows/ci-test.yml) [![release](https://img.shields.io/github/actions/workflow/status/wisarootl/leetcode-py/cd.yml?branch=main&label=release&logo=github)](https://github.com/wisarootl/zerv/actions/workflows/cd.yml) +[![downloads](https://static.pepy.tech/personalized-badge/leetcode-py-sdk?period=total&units=international_system&left_color=grey&right_color=brightgreen&left_text=pypi%20downloads)](https://pepy.tech/projects/leetcode-py-sdk) +[![python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-brightgreen?logo=python)](https://pypi.org/project/leetcode-py-sdk/) A Python package to generate professional LeetCode practice environments. Features automated problem generation from LeetCode URLs, beautiful data structure visualizations (TreeNode, ListNode, GraphNode), and comprehensive testing with 10+ test cases per problem. Built with professional development practices including CI/CD, type hints, and quality gates. **What makes this different:** -- ๐Ÿค– **[LLM-Assisted Workflow](https://github.com/wisarootl/leetcode-py#llm-assisted-problem-creation)**: Generate new problems instantly with AI assistance +- ๐Ÿค– **[LLM-Assisted Workflow](https://github.com/wisarootl/leetcode-py/blob/main/docs/llm-assisted-problem-creation.md)**: Generate new problems instantly with AI assistance - ๐ŸŽจ **Visual Debugging**: Interactive tree/graph rendering with Graphviz and anytree - ๐Ÿงช **Production Testing**: Comprehensive test suites with edge cases and reproducibility verification - ๐Ÿš€ **Modern Python**: PEP 585/604 type hints, Poetry, and professional tooling - ๐Ÿ“Š **Quality Assurance**: 95%+ test coverage, security scanning, automated linting +- โšก **[Powerful CLI](https://github.com/wisarootl/leetcode-py/blob/main/docs/cli-usage.md)**: Generate problems anywhere with `lcpy` command ## ๐ŸŽฏ What's Included **Current**: All 75 problems from [Grind 75](https://www.techinterviewhandbook.org/grind75/) - the most essential coding interview questions curated by the creator of Blind 75. -**Future**: Planned expansion to all free Grind problems for comprehensive interview preparation. +**Future**: Planned expansion to all free Grind problems for comprehensive interview preparation. [Contributions welcome!](CONTRIBUTING.md) ## ๐Ÿš€ Quick Start diff --git a/docs/cli-usage.md b/docs/cli-usage.md index 811beb5..6e3478c 100644 --- a/docs/cli-usage.md +++ b/docs/cli-usage.md @@ -156,10 +156,7 @@ problem_name/ Available tags for bulk operations: - `grind-75` - Essential 75 coding interview problems -- `blind-75` - Original Blind 75 problems -- `neetcode-150` - NeetCode 150 problems -- `top-interview` - Top interview questions -- `easy`, `medium`, `hard` - Difficulty-based tags +- `grind` - Original Blind 75 problems ## Output Directory diff --git a/docs/improvement-checklist.md b/docs/improvement-checklist.md new file mode 100644 index 0000000..8f1fee7 --- /dev/null +++ b/docs/improvement-checklist.md @@ -0,0 +1,133 @@ +# Documentation Improvement Checklist + +## High Priority Fixes + +### README.md Critical Issues + +- [ ] **Fix badge links**: Update tests and release badges from `wisarootl/zerv` to `wisarootl/leetcode-py` +- [ ] **Python version consistency**: Change "Python 3.13+" to "Python 3.10+" to match badge +- [ ] **Fix pip install command**: Update from `pip install leetcode-py` to `pip install leetcode-py-sdk` + +### Navigation & Structure + +- [ ] **Add Table of Contents**: Include TOC at top of README for better navigation +- [ ] **Consolidate CLI sections**: Reduce redundancy between Quick Start, Usage Patterns, and CLI guide +- [ ] **Reorganize sections**: Move Development Setup after CLI usage for better flow + +## Content Enhancements + +### README.md Improvements + +- [ ] **Add "Getting Started in 5 Minutes"**: Absolute minimum steps for new users +- [ ] **Performance metrics**: Add statistics like "Generate 75 problems in under 30 seconds" +- [ ] **User personas**: Different paths for beginner vs advanced developers +- [ ] **Comparison table**: Compare with other LeetCode practice tools +- [ ] **More concrete examples**: Show before/after of problem generation + +### CLI Usage Guide + +- [ ] **Add troubleshooting section**: Common CLI errors and solutions +- [ ] **Performance tips**: Best practices for bulk operations +- [ ] **Combine multiple options**: Examples of complex CLI combinations +- [ ] **Error handling examples**: Show specific error messages and fixes + +### LLM-Assisted Problem Creation Guide + +- [ ] **Prerequisites checklist**: Clear setup requirements at top +- [ ] **Test case verification**: Section on verifying generated test correctness +- [ ] **More prompt examples**: Expand good vs bad prompt examples +- [ ] **Integration examples**: Show how it fits into development workflow + +### CONTRIBUTING.md + +- [ ] **Examples of contribution types**: Clarify "small changes" vs "larger changes" +- [ ] **Link to issue templates**: Reference different contribution types +- [ ] **Development workflow**: More detailed setup and testing instructions + +## New Documentation + +### Missing Documentation Files + +- [ ] **API Reference** (`docs/api-reference.md`): Document helper classes with examples + - TreeNode methods and usage + - ListNode methods and usage + - GraphNode methods and usage + - DictTree methods and usage +- [ ] **Troubleshooting Guide** (`docs/troubleshooting.md`): Common issues and solutions +- [ ] **FAQ** (`docs/faq.md`): Frequently asked questions +- [ ] **Performance Guide** (`docs/performance.md`): Optimization tips and benchmarks + +### Enhanced Examples + +- [ ] **Data structure examples**: Concrete usage of TreeNode, ListNode, etc. +- [ ] **Integration examples**: How to use with existing projects +- [ ] **Advanced usage**: Complex scenarios and edge cases + +## Visual & Media + +### Image Consistency + +- [ ] **Standardize screenshots**: Ensure consistent IDE theme across all images +- [ ] **Update outdated images**: Verify all screenshots reflect current UI +- [ ] **Add missing visuals**: More examples of CLI output and generated files + +### Links & References + +- [ ] **Verify all links**: Check internal and external links work +- [ ] **Add more references**: Link to LeetCode, Grind 75, related tools +- [ ] **Fix image accessibility**: Ensure all images load correctly + +## Technical Improvements + +### SEO & Discoverability + +- [ ] **Improve meta descriptions**: Better GitHub search results +- [ ] **Add keywords**: More searchable terms in descriptions +- [ ] **Tag optimization**: Better categorization and tagging + +### Code Quality + +- [ ] **Code example validation**: Ensure all code snippets work +- [ ] **Import statement examples**: Show correct import patterns +- [ ] **Error handling**: Better error message examples + +## Organization & Maintenance + +### File Structure + +- [ ] **Organize docs folder**: Better categorization of documentation +- [ ] **Cross-references**: Better linking between related docs +- [ ] **Version consistency**: Ensure all docs reflect current version + +### Content Maintenance + +- [ ] **Regular review schedule**: Plan for keeping docs updated +- [ ] **User feedback integration**: Process for incorporating user suggestions +- [ ] **Automated checks**: Validate links and code examples in CI + +## Implementation Priority + +### Phase 1 (Immediate) + +1. Fix badge links +2. Update Python version consistency +3. Fix pip install command +4. Add Table of Contents + +### Phase 2 (Short-term) + +1. Create API reference +2. Add troubleshooting guide +3. Enhance CLI documentation +4. Improve visual consistency + +### Phase 3 (Long-term) + +1. Create comprehensive FAQ +2. Add performance guide +3. Develop user persona paths +4. Build comparison resources + +--- + +**Note**: This checklist should be reviewed and updated regularly as the project evolves and user feedback is received. From 61dea9827614c2b16737d09ab0e2e731db3c24d7 Mon Sep 17 00:00:00 2001 From: Wisaroot Lertthaweedech Date: Wed, 17 Sep 2025 08:51:07 +0700 Subject: [PATCH 2/4] docs: improve docs --- README.md | 54 +++++++-------- docs/improvement-checklist.md | 119 +++------------------------------- 2 files changed, 35 insertions(+), 138 deletions(-) diff --git a/README.md b/README.md index 38e11f6..1a936f7 100644 --- a/README.md +++ b/README.md @@ -4,13 +4,26 @@ [![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=wisarootl_leetcode-py&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=wisarootl_leetcode-py) [![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=wisarootl_leetcode-py&metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=wisarootl_leetcode-py) [![codecov](https://codecov.io/gh/wisarootl/leetcode-py/graph/badge.svg?token=TI97VUIA4Z)](https://codecov.io/gh/wisarootl/leetcode-py) -[![tests](https://img.shields.io/github/actions/workflow/status/wisarootl/leetcode-py/ci-test.yml?branch=main&label=tests&logo=github)](https://github.com/wisarootl/zerv/actions/workflows/ci-test.yml) -[![release](https://img.shields.io/github/actions/workflow/status/wisarootl/leetcode-py/cd.yml?branch=main&label=release&logo=github)](https://github.com/wisarootl/zerv/actions/workflows/cd.yml) +[![tests](https://img.shields.io/github/actions/workflow/status/wisarootl/leetcode-py/ci-test.yml?branch=main&label=tests&logo=github)](https://github.com/wisarootl/leetcode-py/actions/workflows/ci-test.yml) +[![release](https://img.shields.io/github/actions/workflow/status/wisarootl/leetcode-py/cd.yml?branch=main&label=release&logo=github)](https://github.com/wisarootl/leetcode-py/actions/workflows/cd.yml) [![downloads](https://static.pepy.tech/personalized-badge/leetcode-py-sdk?period=total&units=international_system&left_color=grey&right_color=brightgreen&left_text=pypi%20downloads)](https://pepy.tech/projects/leetcode-py-sdk) [![python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-brightgreen?logo=python)](https://pypi.org/project/leetcode-py-sdk/) A Python package to generate professional LeetCode practice environments. Features automated problem generation from LeetCode URLs, beautiful data structure visualizations (TreeNode, ListNode, GraphNode), and comprehensive testing with 10+ test cases per problem. Built with professional development practices including CI/CD, type hints, and quality gates. +## Table of Contents + +- [What's Included](#-whats-included) +- [Quick Start](#-quick-start) +- [Problem Structure](#-problem-structure) +- [Key Features](#-key-features) +- [Usage Patterns](#-usage-patterns) +- [Helper Classes](#-helper-classes) +- [Commands](#๏ธ-commands) +- [Development Setup](#๏ธ-development-setup) +- [Architecture](#๏ธ-architecture) +- [Quality Metrics](#-quality-metrics) + **What makes this different:** - ๐Ÿค– **[LLM-Assisted Workflow](https://github.com/wisarootl/leetcode-py/blob/main/docs/llm-assisted-problem-creation.md)**: Generate new problems instantly with AI assistance @@ -30,15 +43,12 @@ A Python package to generate professional LeetCode practice environments. Featur ### System Requirements -- **Python 3.13+** - Modern Python runtime with latest type system features -- **Poetry** - Dependency management and packaging -- **Make** - Build automation (development workflows) -- **Git** - Version control system -- **Graphviz** - Graph visualization library (for data structure rendering) +- **Python 3.10+** - Python runtime +- **Graphviz** - Graph visualization library ([install guide](https://graphviz.org/download/)) ```bash # Install the package -pip install leetcode-py +pip install leetcode-py-sdk # Generate problems anywhere lcpy gen -n 1 # Generate Two Sum @@ -150,30 +160,20 @@ _Interactive multi-cell playground with rich data structure visualization for ea ### CLI Usage (Global Installation) -Perfect for quick problem generation anywhere: - -```bash -# Generate specific problems -lcpy gen -n 1 -n 125 -n 206 # Multiple problems by number -lcpy gen -s two-sum -s valid-palindrome # Multiple problems by slug - -# Bulk generation -lcpy gen -t grind-75 # All Grind 75 problems -lcpy gen -t grind-75 -d Easy # Only Easy problems from Grind 75 - -# Explore available problems -lcpy list # All problems -lcpy list -t grind-75 # Filter by tag -lcpy list -d Medium # Filter by difficulty - -# Fetch problem data -lcpy scrape -n 1 > two_sum.json # Save problem data -``` +Perfect for quick problem generation anywhere. See the ๐Ÿ“– **[Complete CLI Usage Guide](https://github.com/wisarootl/leetcode-py/blob/main/docs/cli-usage.md)** for detailed documentation with all options and examples. ## ๐Ÿ› ๏ธ Development Setup For working within this repository to generate additional LeetCode problems using LLM assistance: +### Development Requirements + +- **Python 3.10+** - Modern Python runtime with latest type system features +- **Poetry** - Dependency management and packaging +- **Make** - Build automation (development workflows) +- **Git** - Version control system +- **Graphviz** - Graph visualization library ([install guide](https://graphviz.org/download/)) + ```bash # Clone repository for development git clone https://github.com/wisarootl/leetcode-py.git diff --git a/docs/improvement-checklist.md b/docs/improvement-checklist.md index 8f1fee7..194387a 100644 --- a/docs/improvement-checklist.md +++ b/docs/improvement-checklist.md @@ -4,130 +4,27 @@ ### README.md Critical Issues -- [ ] **Fix badge links**: Update tests and release badges from `wisarootl/zerv` to `wisarootl/leetcode-py` -- [ ] **Python version consistency**: Change "Python 3.13+" to "Python 3.10+" to match badge -- [ ] **Fix pip install command**: Update from `pip install leetcode-py` to `pip install leetcode-py-sdk` +- [x] **Fix badge links**: Update tests and release badges from `wisarootl/zerv` to `wisarootl/leetcode-py` +- [x] **Python version consistency**: Change "Python 3.13+" to "Python 3.10+" to match badge +- [x] **Fix pip install command**: Update from `pip install leetcode-py` to `pip install leetcode-py-sdk` ### Navigation & Structure -- [ ] **Add Table of Contents**: Include TOC at top of README for better navigation -- [ ] **Consolidate CLI sections**: Reduce redundancy between Quick Start, Usage Patterns, and CLI guide -- [ ] **Reorganize sections**: Move Development Setup after CLI usage for better flow +- [x] **Add Table of Contents**: Include TOC at top of README for better navigation +- [x] **Consolidate CLI sections**: Reduce redundancy between Quick Start, Usage Patterns, and CLI guide +- [x] **Reorganize sections**: Move Development Setup after CLI usage for better flow ## Content Enhancements ### README.md Improvements -- [ ] **Add "Getting Started in 5 Minutes"**: Absolute minimum steps for new users -- [ ] **Performance metrics**: Add statistics like "Generate 75 problems in under 30 seconds" -- [ ] **User personas**: Different paths for beginner vs advanced developers -- [ ] **Comparison table**: Compare with other LeetCode practice tools -- [ ] **More concrete examples**: Show before/after of problem generation - -### CLI Usage Guide - -- [ ] **Add troubleshooting section**: Common CLI errors and solutions -- [ ] **Performance tips**: Best practices for bulk operations -- [ ] **Combine multiple options**: Examples of complex CLI combinations -- [ ] **Error handling examples**: Show specific error messages and fixes +- [x] **Fix Quick Start system requirements**: Change from development requirements (Poetry/Make/Git) to CLI usage requirements (Python + Graphviz from https://graphviz.org/download/) +- [x] **Move development system requirements**: Add proper development requirements to Development Setup section ### LLM-Assisted Problem Creation Guide -- [ ] **Prerequisites checklist**: Clear setup requirements at top - [ ] **Test case verification**: Section on verifying generated test correctness -- [ ] **More prompt examples**: Expand good vs bad prompt examples -- [ ] **Integration examples**: Show how it fits into development workflow ### CONTRIBUTING.md -- [ ] **Examples of contribution types**: Clarify "small changes" vs "larger changes" -- [ ] **Link to issue templates**: Reference different contribution types - [ ] **Development workflow**: More detailed setup and testing instructions - -## New Documentation - -### Missing Documentation Files - -- [ ] **API Reference** (`docs/api-reference.md`): Document helper classes with examples - - TreeNode methods and usage - - ListNode methods and usage - - GraphNode methods and usage - - DictTree methods and usage -- [ ] **Troubleshooting Guide** (`docs/troubleshooting.md`): Common issues and solutions -- [ ] **FAQ** (`docs/faq.md`): Frequently asked questions -- [ ] **Performance Guide** (`docs/performance.md`): Optimization tips and benchmarks - -### Enhanced Examples - -- [ ] **Data structure examples**: Concrete usage of TreeNode, ListNode, etc. -- [ ] **Integration examples**: How to use with existing projects -- [ ] **Advanced usage**: Complex scenarios and edge cases - -## Visual & Media - -### Image Consistency - -- [ ] **Standardize screenshots**: Ensure consistent IDE theme across all images -- [ ] **Update outdated images**: Verify all screenshots reflect current UI -- [ ] **Add missing visuals**: More examples of CLI output and generated files - -### Links & References - -- [ ] **Verify all links**: Check internal and external links work -- [ ] **Add more references**: Link to LeetCode, Grind 75, related tools -- [ ] **Fix image accessibility**: Ensure all images load correctly - -## Technical Improvements - -### SEO & Discoverability - -- [ ] **Improve meta descriptions**: Better GitHub search results -- [ ] **Add keywords**: More searchable terms in descriptions -- [ ] **Tag optimization**: Better categorization and tagging - -### Code Quality - -- [ ] **Code example validation**: Ensure all code snippets work -- [ ] **Import statement examples**: Show correct import patterns -- [ ] **Error handling**: Better error message examples - -## Organization & Maintenance - -### File Structure - -- [ ] **Organize docs folder**: Better categorization of documentation -- [ ] **Cross-references**: Better linking between related docs -- [ ] **Version consistency**: Ensure all docs reflect current version - -### Content Maintenance - -- [ ] **Regular review schedule**: Plan for keeping docs updated -- [ ] **User feedback integration**: Process for incorporating user suggestions -- [ ] **Automated checks**: Validate links and code examples in CI - -## Implementation Priority - -### Phase 1 (Immediate) - -1. Fix badge links -2. Update Python version consistency -3. Fix pip install command -4. Add Table of Contents - -### Phase 2 (Short-term) - -1. Create API reference -2. Add troubleshooting guide -3. Enhance CLI documentation -4. Improve visual consistency - -### Phase 3 (Long-term) - -1. Create comprehensive FAQ -2. Add performance guide -3. Develop user persona paths -4. Build comparison resources - ---- - -**Note**: This checklist should be reviewed and updated regularly as the project evolves and user feedback is received. From 800410e662be9d08563ee43c4699a2455ca0e562 Mon Sep 17 00:00:00 2001 From: Wisaroot Lertthaweedech Date: Wed, 17 Sep 2025 09:07:20 +0700 Subject: [PATCH 3/4] docs: improve docs --- CONTRIBUTING.md | 61 +++++++++++++++++++++++---- README.md | 3 +- docs/cli-usage.md | 28 +++++++++++- docs/improvement-checklist.md | 30 ------------- docs/llm-assisted-problem-creation.md | 22 +++++----- 5 files changed, 92 insertions(+), 52 deletions(-) delete mode 100644 docs/improvement-checklist.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d990e98..78d51bf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -37,21 +37,66 @@ I'm also open to feedback and suggestions for improving the project! ## Development Setup +### Prerequisites + +- **Python 3.10+** - Modern Python runtime +- **Poetry** - Dependency management ([install guide](https://python-poetry.org/docs/#installation)) +- **Make** - Build automation (usually pre-installed on Unix systems) +- **Git** - Version control +- **Graphviz** - Graph visualization ([install guide](https://graphviz.org/download/)) + +## Development Workflow + +### 1. Fork and Setup + ```bash -git clone https://github.com/wisarootl/leetcode-py.git +# Fork the repository on GitHub, then clone your fork +git clone https://github.com/YOUR_USERNAME/leetcode-py.git cd leetcode-py poetry install + +# Add upstream remote +git remote add upstream https://github.com/wisarootl/leetcode-py.git + +# Verify setup +make test +make lint +``` + +### 2. Create Feature Branch + +```bash +git checkout -b your-feature-name +``` + +### 3. Make Changes and Test + +```bash +# Test specific problem +make p-test PROBLEM=problem_name + +# Test all make test + +# Lint your changes +make lint + +# Generate/regenerate problems (if needed) +make p-gen PROBLEM=problem_name ``` -## Pull Request Process +### 4. Submit Pull Request + +```bash +# Commit and push to your fork +git add . +git commit -m "feat: your descriptive commit message" +git push origin your-feature-name + +# Then create a pull request on GitHub from your fork to the main repository +``` -1. Fork the repository -2. Create a feature branch -3. Make your changes -4. Run `make lint` and `make test` -5. Ensure all GitHub Actions CI checks pass -6. Submit a pull request with clear description +**Ensure all GitHub Actions CI checks pass before requesting review.** ## Questions? diff --git a/README.md b/README.md index 1a936f7..25b9e40 100644 --- a/README.md +++ b/README.md @@ -54,7 +54,6 @@ pip install leetcode-py-sdk lcpy gen -n 1 # Generate Two Sum lcpy gen -t grind-75 # Generate all Grind 75 problems lcpy list -t grind-75 # List available problems -lcpy scrape -n 1 # Fetch problem data # Start practicing cd leetcode/two_sum @@ -62,7 +61,7 @@ python -m pytest test_solution.py # Run tests # Edit solution.py, then rerun tests ``` -### Example +### Bulk Generation Example ```bash lcpy gen --problem-tag grind-75 --output leetcode # Generate all Grind 75 problems diff --git a/docs/cli-usage.md b/docs/cli-usage.md index 6e3478c..ca91ff3 100644 --- a/docs/cli-usage.md +++ b/docs/cli-usage.md @@ -65,9 +65,23 @@ lcpy gen -s two-sum # Multiple problems by slug lcpy gen -s two-sum -s valid-palindrome -# All problems with specific tag +# All problems with specific tag (bulk generation) lcpy gen -t grind-75 +# Example: Generate all Grind 75 problems +lcpy gen --problem-tag grind-75 --output leetcode +``` + +![Problem Generation](https://raw.githubusercontent.com/wisarootl/leetcode-py/main/docs/images/problems-generation.png) + +_Bulk generation output showing "Generated problem:" messages for all 75 Grind problems_ + +![Problem Generation 2](https://raw.githubusercontent.com/wisarootl/leetcode-py/main/docs/images/problems-generation-2.png) + +_Generated folder structure showing all 75 problem directories after command execution_ + +```bash + # Filter by difficulty lcpy gen -t grind-75 -d Easy @@ -151,6 +165,18 @@ problem_name/ โ””โ”€โ”€ __init__.py # Package marker ``` +![README Example](https://raw.githubusercontent.com/wisarootl/leetcode-py/main/docs/images/readme-example.png) + +_README format that mirrors LeetCode's problem description layout_ + +![Solution Boilerplate](https://raw.githubusercontent.com/wisarootl/leetcode-py/main/docs/images/solution-boilerplate.png) + +_Solution boilerplate with type hints and TODO placeholder_ + +![Test Example](https://raw.githubusercontent.com/wisarootl/leetcode-py/main/docs/images/test-example.png) + +_Comprehensive parametrized tests with 10+ test cases - executable and debuggable in local development environment_ + ## Tags Available tags for bulk operations: diff --git a/docs/improvement-checklist.md b/docs/improvement-checklist.md deleted file mode 100644 index 194387a..0000000 --- a/docs/improvement-checklist.md +++ /dev/null @@ -1,30 +0,0 @@ -# Documentation Improvement Checklist - -## High Priority Fixes - -### README.md Critical Issues - -- [x] **Fix badge links**: Update tests and release badges from `wisarootl/zerv` to `wisarootl/leetcode-py` -- [x] **Python version consistency**: Change "Python 3.13+" to "Python 3.10+" to match badge -- [x] **Fix pip install command**: Update from `pip install leetcode-py` to `pip install leetcode-py-sdk` - -### Navigation & Structure - -- [x] **Add Table of Contents**: Include TOC at top of README for better navigation -- [x] **Consolidate CLI sections**: Reduce redundancy between Quick Start, Usage Patterns, and CLI guide -- [x] **Reorganize sections**: Move Development Setup after CLI usage for better flow - -## Content Enhancements - -### README.md Improvements - -- [x] **Fix Quick Start system requirements**: Change from development requirements (Poetry/Make/Git) to CLI usage requirements (Python + Graphviz from https://graphviz.org/download/) -- [x] **Move development system requirements**: Add proper development requirements to Development Setup section - -### LLM-Assisted Problem Creation Guide - -- [ ] **Test case verification**: Section on verifying generated test correctness - -### CONTRIBUTING.md - -- [ ] **Development workflow**: More detailed setup and testing instructions diff --git a/docs/llm-assisted-problem-creation.md b/docs/llm-assisted-problem-creation.md index f4d770f..bb97d3b 100644 --- a/docs/llm-assisted-problem-creation.md +++ b/docs/llm-assisted-problem-creation.md @@ -75,27 +75,25 @@ Each problem includes 10+ test cases covering edge cases (note: generated test c _Generated test_solution.py with parametrized tests and comprehensive test cases_ -## Test Enhancement Workflow +## Test Enhancement & Verification -### Enhancing Existing Problems +### Enhancing and Verifying Test Cases -Improve test coverage for existing problems: +Improve test coverage and verify correctness for existing or newly generated problems: + +**1. Run the tests:** ```bash -"Enhance test cases for two_sum problem" -"Add more edge cases to binary_tree_inorder_traversal" -"Fix test reproducibility for valid_palindrome" +make p-test PROBLEM={problem_name} ``` -### Quality Assurance - -The assistant can identify problems needing more test cases and verify test case correctness and reproducibility: +**2. Ask LLM to enhance or verify:** ```bash +"Enhance test cases for {problem_name} problem" +"Fix test reproducibility for {problem_name}" "Check which problems need more test cases" "Find problems with less than 12 test cases" -"Verify test case correctness for house_robber" -"Fix test reproducibility for binary_tree_inorder_traversal" ``` ## Best Practices @@ -107,11 +105,13 @@ The assistant can identify problems needing more test cases and verify test case - "Add problem 198. House Robber with grind tag" - "Create problem 70. Climbing Stairs for grind-75" - "Enhance test cases for two_sum problem" +- "Verify and fix test cases for binary_search problem" **Avoid:** - Vague requests without problem numbers - Requests for non-existent problems +- Assuming generated test cases are always correct ## Troubleshooting From dc201a3e4757d23451eae8222170b8a959cd2a27 Mon Sep 17 00:00:00 2001 From: Wisaroot Lertthaweedech Date: Wed, 17 Sep 2025 09:14:57 +0700 Subject: [PATCH 4/4] docs: improve docs --- README.md | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 25b9e40..58fb42b 100644 --- a/README.md +++ b/README.md @@ -13,16 +13,16 @@ A Python package to generate professional LeetCode practice environments. Featur ## Table of Contents -- [What's Included](#-whats-included) -- [Quick Start](#-quick-start) -- [Problem Structure](#-problem-structure) -- [Key Features](#-key-features) -- [Usage Patterns](#-usage-patterns) -- [Helper Classes](#-helper-classes) -- [Commands](#๏ธ-commands) -- [Development Setup](#๏ธ-development-setup) -- [Architecture](#๏ธ-architecture) -- [Quality Metrics](#-quality-metrics) +- [What's Included](#whats-included) +- [Quick Start](#quick-start) +- [Problem Structure](#problem-structure) +- [Key Features](#key-features) +- [Usage Patterns](#usage-patterns) +- [Development Setup](#development-setup) +- [Helper Classes](#helper-classes) +- [Commands](#commands) +- [Architecture](#architecture) +- [Quality Metrics](#quality-metrics) **What makes this different:** @@ -33,13 +33,13 @@ A Python package to generate professional LeetCode practice environments. Featur - ๐Ÿ“Š **Quality Assurance**: 95%+ test coverage, security scanning, automated linting - โšก **[Powerful CLI](https://github.com/wisarootl/leetcode-py/blob/main/docs/cli-usage.md)**: Generate problems anywhere with `lcpy` command -## ๐ŸŽฏ What's Included +## ๐ŸŽฏ What's Included **Current**: All 75 problems from [Grind 75](https://www.techinterviewhandbook.org/grind75/) - the most essential coding interview questions curated by the creator of Blind 75. **Future**: Planned expansion to all free Grind problems for comprehensive interview preparation. [Contributions welcome!](CONTRIBUTING.md) -## ๐Ÿš€ Quick Start +## ๐Ÿš€ Quick Start ### System Requirements @@ -75,7 +75,7 @@ _Bulk generation output showing "Generated problem:" messages for all 75 Grind p _Generated folder structure showing all 75 problem directories after command execution_ -## ๐Ÿ“ Problem Structure +## ๐Ÿ“ Problem Structure Each problem follows a consistent, production-ready template: @@ -105,7 +105,7 @@ _Comprehensive parametrized tests with 10+ test cases - executable and debuggabl _Beautiful colorful test output with loguru integration for enhanced debugging and test result visualization_ -## โœจ Key Features +## โœจ Key Features ### Production-Grade Development Environment @@ -155,13 +155,13 @@ _Simple arrow-based list representation for console output and test debugging_ _Interactive multi-cell playground with rich data structure visualization for each problem_ -## ๐Ÿ”„ Usage Patterns +## ๐Ÿ”„ Usage Patterns ### CLI Usage (Global Installation) Perfect for quick problem generation anywhere. See the ๐Ÿ“– **[Complete CLI Usage Guide](https://github.com/wisarootl/leetcode-py/blob/main/docs/cli-usage.md)** for detailed documentation with all options and examples. -## ๐Ÿ› ๏ธ Development Setup +## ๐Ÿ› ๏ธ Development Setup For working within this repository to generate additional LeetCode problems using LLM assistance: