docs: streamline documentation for clarity and automation (#28)

dreamiurg · claude · web-flow · commit 28c6181c0e8e · 2025-10-25T12:46:37.000-07:00
Simplified README.md to focus on end-users: - Removed project structure and development sections - Removed technical implementation details (dependencies, how it works) - Simplified introduction and features list - Removed redundant Contributing section (added reference early instead) - Added early reference to CONTRIBUTING.md Updated CONTRIBUTING.md to reflect automated release process: - Removed pre-commit installation from basic setup - Removed detailed pre-commit hooks section - Emphasized automated releases via GitHub Actions - Clarified manual releases are fallback only - Removed manual version override and troubleshooting sections Net result: Removed 124 lines of developer-focused content, making documentation more concise and user-focused. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude <noreply@anthropic.com>
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -16,9 +16,6 @@ curl -LsSf https://astral.sh/uv/install.sh | sh
 # Set up the development environment
 uv sync
 
-# Install pre-commit hooks
-uv run pre-commit install
-
 # Run the CLI
 uv run peakbagger --help
 ```
@@ -32,9 +29,6 @@ source .venv/bin/activate  # On Windows: .venv\Scripts\activate
 
 # Install in editable mode with dev dependencies
 pip install -e ".[dev]"
-
-# Install pre-commit hooks
-pre-commit install
 ```
 
 ## Project Structure
@@ -63,26 +57,7 @@ peakbagger-cli/
 
 ## Code Quality
 
-### Pre-commit Hooks
-
-Pre-commit hooks automatically check code before commits:
-
-```bash
-# Install hooks (one time setup)
-uv run pre-commit install
-
-# Run manually on all files
-uv run pre-commit run --all-files
-```
-
-**Hooks verify:**
-
-- **Ruff**: Formatting and linting (replaces Black, isort, flake8)
-- **Bandit**: Security vulnerability checks
-- **mypy**: Type checking
-- File hygiene (trailing whitespace, end of file newlines, etc.)
-
-### Manual Formatting and Linting
+### Formatting and Linting
 
 ```bash
 # Format code
@@ -146,7 +121,18 @@ When updating scraper logic:
 1. Test parsing locally without network requests
 1. Update tests with new HTML structure
 
-## Release Process (Maintainers Only)
+## Release Process
+
+### Automated Releases (Default)
+
+**Releases are fully automated via GitHub Actions.** When commits are merged to the `main` branch:
+
+1. GitHub Actions analyzes commit messages
+2. If a release-triggering commit is found, the version is bumped automatically
+3. CHANGELOG.md is updated
+4. A Git tag and GitHub release are created
+
+**No manual intervention needed** - just merge your PR with a conventional commit message.
 
 ### Commit Message Format
 
@@ -186,23 +172,16 @@ git commit -m "feat: redesign CLI interface
 BREAKING CHANGE: The --full flag has been replaced with --detailed"
 ```
 
-### Creating a Release
+### Manual Release (Fallback Only)
+
+Manual releases are rarely needed but available for testing or troubleshooting:
 
 ```bash
 # Preview what would be released
 uv run semantic-release version --print
 
-# Create the release (updates version, changelog, creates tag)
-uv run semantic-release version
-
-# Build the package
-uv build
-
-# Publish to PyPI
-uv tool run twine upload dist/*
-
-# Create GitHub release
-gh release create v0.2.0 --notes-from-tag
+# Create release locally (testing/development only)
+uv run semantic-release version --no-push --no-vcs-release
 ```
 
 ### Version Bumping Examples
@@ -215,36 +194,6 @@ gh release create v0.2.0 --notes-from-tag
 | Multiple `fix:` commits | 3x `fix:` commits | `0.1.1` (single bump) |
 | `fix:` + `feat:` | Both types present | `0.2.0` (highest bump wins) |
 
-### Manual Version Override
-
-```bash
-# Force a specific bump type
-uv run semantic-release version --patch
-uv run semantic-release version --minor
-uv run semantic-release version --major
-
-# Set exact version
-uv run semantic-release version --bump-version 0.3.0
-```
-
-### Troubleshooting Releases
-
-#### "No release will be made"
-
-- No commits since last release follow conventional format
-- Add a conventional commit or use `--patch/--minor/--major` flag
-
-#### "Token value is missing"
-
-- This warning is safe to ignore for manual releases
-- Only needed for GitHub Actions automation
-
-#### Wrong version calculated
-
-- Review commits: `git log v0.1.0..HEAD --oneline`
-- Check commit types match conventional format
-- Use `--noop` flag to preview before committing
-
 ## License
 
 Contributing to peakbagger-cli means your contributions receive MIT License terms.
diff --git a/README.md b/README.md
@@ -6,21 +6,20 @@
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/dreamiurg/peakbagger-cli/blob/main/LICENSE)
 [![Types: Typed](https://img.shields.io/badge/types-typed-brightgreen.svg)](https://github.com/dreamiurg/peakbagger-cli/blob/main/peakbagger)
 
-A modern command-line interface for searching and retrieving mountain peak data from [PeakBagger.com](https://www.peakbagger.com).
-
-Python 3.12+, Click, and Rich deliver a beautiful terminal experience.
+A command-line interface for searching and retrieving mountain peak data from [PeakBagger.com](https://www.peakbagger.com).
 
 ## Features
 
 - 🔍 **Search peaks** by name with instant results
 - 📊 **Detailed peak info** including elevation, prominence, isolation, and location
 - 📈 **Ascent statistics** - analyze climbing activity, seasonal patterns, and trip reports
-- 🎨 **Beautiful output** with Rich-formatted tables and colors
+- 🎨 **Beautiful output** with formatted tables and colors
 - 🤖 **JSON output** for automation and scripting
-- ⚡ **Fast and modern** using `uv` for dependency management and Pydantic models
 - 🛡️ **Respectful scraping** with configurable rate limiting
 - 🌐 **Cloudflare bypass** for reliable access
 
+> **For contributors**: See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, code guidelines, and release process.
+
 ## Installation
 
 ### Using uvx (Recommended - No Installation Required)
@@ -584,76 +583,10 @@ peakbagger peak search "Rainier" --rate-limit 3.0
 peakbagger peak show 2296 --rate-limit 1.0
 ```
 
-## Project Structure
-
-```text
-peakbagger-cli/
-├── peakbagger/
-│   ├── __init__.py        # Package metadata
-│   ├── cli.py             # Click CLI commands
-│   ├── client.py          # HTTP client with rate limiting
-│   ├── scraper.py         # HTML parsing logic
-│   ├── models.py          # Data models
-│   ├── formatters.py      # Output formatting (Rich/JSON)
-│   └── logging_config.py  # Logging configuration
-├── tests/                 # Test suite (coming soon)
-├── pyproject.toml         # Project configuration
-├── README.md              # This file
-├── CONTRIBUTING.md        # Contribution guide
-└── LICENSE                # MIT License
-```
-
-## Development
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed development guidelines.
-
-### Quick Setup
+## Data Source
 
-```bash
-# Clone the repository
-git clone https://github.com/yourusername/peakbagger-cli.git
-cd peakbagger-cli
-
-# Set up development environment with uv
-uv sync
-
-# Run the CLI
-uv run peakbagger --help
-```
-
-### Running Commands
-
-```bash
-# Run CLI commands during development
-uv run peakbagger peak search "Rainier"
-uv run peakbagger peak show 2296
-
-# Check version
-uv run peakbagger --version
-```
-
-## Technical Details
-
-### Dependencies
-
-- **Click**: CLI framework
-- **cloudscraper**: Cloudflare bypass for HTTP requests
-- **BeautifulSoup4**: HTML parsing
-- **lxml**: Fast XML/HTML parser
-- **Rich**: Beautiful terminal output
-- **loguru**: Simple and powerful logging
-
-### How It Works
-
-1. **Search**: Queries PeakBagger.com's search endpoint with your query
-2. **Parse**: Extracts peak information from HTML using BeautifulSoup
-3. **Format**: Displays results as Rich tables (text) or JSON
-4. **Rate Limit**: Waits between requests to respect the server
-
-### Data Sources
-
-This tool scrapes all data from [PeakBagger.com](https://www.peakbagger.com), which
-aggregates peak information from USGS, LIDAR data, and user contributions.
+All data is scraped from [PeakBagger.com](https://www.peakbagger.com).
+The site aggregates peak information from USGS, LIDAR data, and user contributions.
 
 ## Limitations
 
@@ -699,11 +632,6 @@ Verify Python 3.12+ installation:
 python3 --version  # Should be 3.12 or higher
 ```
 
-## Contributing
-
-Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup,
-code style guidelines, and submission instructions.
-
 ## Support
 
 - **Bug Reports & Feature Requests**: [GitHub Issues](https://github.com/yourusername/peakbagger-cli/issues)
