docs: improve docs (#49)

wislertt · web-flow · commit 68521e3cf135 · 2025-09-17T09:17:57.000+07:00
- update README.md, CONTRIBUTING.md, docs/cli-usage.md,
docs/llm-assisted-problem-creation.md
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -6,50 +6,97 @@ 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
 
+### 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
 ```
 
-## Code Standards
+### 2. Create Feature Branch
+
+```bash
+git checkout -b your-feature-name
+```
 
-- 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
+### 3. Make Changes and Test
 
-## Pull Request Process
+```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
+```
+
+### 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. 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
@@ -4,52 +4,64 @@
 [![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)
+- [Development Setup](#development-setup)
+- [Helper Classes](#helper-classes)
+- [Commands](#commands)
+- [Architecture](#architecture)
+- [Quality Metrics](#quality-metrics)
+
 **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
+## <a id="whats-included"></a>🎯 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
+## <a id="quick-start"></a>🚀 Quick Start
 
 ### 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
 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
 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
@@ -63,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
+## <a id="problem-structure"></a>📁 Problem Structure
 
 Each problem follows a consistent, production-ready template:
 
@@ -93,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
+## <a id="key-features"></a>✨ Key Features
 
 ### Production-Grade Development Environment
 
@@ -143,33 +155,23 @@ _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
+## <a id="usage-patterns"></a>🔄 Usage Patterns
 
 ### 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
+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.
 
-# Explore available problems
-lcpy list                         # All problems
-lcpy list -t grind-75            # Filter by tag
-lcpy list -d Medium              # Filter by difficulty
+## <a id="development-setup"></a>🛠️ Development Setup
 
-# Fetch problem data
-lcpy scrape -n 1 > two_sum.json  # Save problem data
-```
+For working within this repository to generate additional LeetCode problems using LLM assistance:
 
-## 🛠️ Development Setup
+### Development Requirements
 
-For working within this repository to generate additional LeetCode problems using LLM assistance:
+- **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
diff --git 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,15 +165,24 @@ 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:
 
 - `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/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
 
