Initial commit
This commit is contained in:
Zhongwei Li
332
skills/python-project-setup/readme-template.md
Normal file
332
skills/python-project-setup/readme-template.md
Normal file
@@ -0,0 +1,332 @@
|
||||
# README.md Template
|
||||
|
||||
```markdown
|
||||
# Project Name
|
||||
|
||||
Brief one-line description of what this project does.
|
||||
|
||||
## Overview
|
||||
|
||||
A more detailed description of the project, its purpose, and key features.
|
||||
|
||||
## Features
|
||||
|
||||
- Feature 1: Description
|
||||
- Feature 2: Description
|
||||
- Feature 3: Description
|
||||
|
||||
## Requirements
|
||||
|
||||
- Python 3.11 or higher
|
||||
- uv package manager
|
||||
|
||||
## Installation
|
||||
|
||||
### Using uv (Recommended)
|
||||
|
||||
\`\`\`bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/username/project-name.git
|
||||
cd project-name
|
||||
|
||||
# Install dependencies
|
||||
uv sync
|
||||
|
||||
# Activate virtual environment (optional, uv runs commands automatically)
|
||||
source .venv/bin/activate # On Unix/macOS
|
||||
.venv\Scripts\activate # On Windows
|
||||
\`\`\`
|
||||
|
||||
### Using pip
|
||||
|
||||
\`\`\`bash
|
||||
pip install -e .
|
||||
\`\`\`
|
||||
|
||||
## Quick Start
|
||||
|
||||
\`\`\`python
|
||||
from project_name import main_function
|
||||
|
||||
# Example usage
|
||||
result = main_function()
|
||||
print(result)
|
||||
\`\`\`
|
||||
|
||||
## Usage
|
||||
|
||||
### Command Line Interface
|
||||
|
||||
\`\`\`bash
|
||||
# Run the main application
|
||||
uv run python -m project_name
|
||||
|
||||
# Or if you installed with pip
|
||||
project-cli --help
|
||||
\`\`\`
|
||||
|
||||
### As a Library
|
||||
|
||||
\`\`\`python
|
||||
from project_name import SomeClass
|
||||
|
||||
# Create an instance
|
||||
instance = SomeClass(param="value")
|
||||
|
||||
# Use the instance
|
||||
result = instance.method()
|
||||
\`\`\`
|
||||
|
||||
## Development
|
||||
|
||||
### Setup Development Environment
|
||||
|
||||
\`\`\`bash
|
||||
# Install with development dependencies
|
||||
uv sync --extra dev
|
||||
|
||||
# Or install all extras
|
||||
uv sync --all-extras
|
||||
\`\`\`
|
||||
|
||||
### Running Tests
|
||||
|
||||
\`\`\`bash
|
||||
# Run all tests
|
||||
uv run pytest
|
||||
|
||||
# Run with coverage
|
||||
uv run pytest --cov
|
||||
|
||||
# Run specific test file
|
||||
uv run pytest tests/test_specific.py
|
||||
|
||||
# Run with verbose output
|
||||
uv run pytest -v
|
||||
\`\`\`
|
||||
|
||||
### Code Quality
|
||||
|
||||
\`\`\`bash
|
||||
# Lint code
|
||||
uv run ruff check .
|
||||
|
||||
# Fix auto-fixable issues
|
||||
uv run ruff check --fix .
|
||||
|
||||
# Format code
|
||||
uv run ruff format .
|
||||
|
||||
# Type checking
|
||||
uv run mypy src
|
||||
\`\`\`
|
||||
|
||||
### Pre-commit Checks
|
||||
|
||||
Before committing, ensure all checks pass:
|
||||
|
||||
\`\`\`bash
|
||||
# Run all checks
|
||||
uv run ruff check . && uv run ruff format . && uv run mypy src && uv run pytest
|
||||
\`\`\`
|
||||
|
||||
## Project Structure
|
||||
|
||||
\`\`\`
|
||||
project-name/
|
||||
├── src/
|
||||
│ └── project_name/ # Main package
|
||||
│ ├── __init__.py
|
||||
│ ├── main.py # Entry point
|
||||
│ ├── models/ # Data models
|
||||
│ ├── services/ # Business logic
|
||||
│ └── utils/ # Utilities
|
||||
├── tests/ # Test files
|
||||
├── docs/ # Documentation
|
||||
├── pyproject.toml # Project configuration
|
||||
└── README.md # This file
|
||||
\`\`\`
|
||||
|
||||
## Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
Create a `.env` file in the project root:
|
||||
|
||||
\`\`\`env
|
||||
API_KEY=your_api_key_here
|
||||
DATABASE_URL=postgresql://user:pass@localhost/dbname
|
||||
DEBUG=false
|
||||
\`\`\`
|
||||
|
||||
### Configuration File
|
||||
|
||||
Alternatively, create a `config.yaml`:
|
||||
|
||||
\`\`\`yaml
|
||||
api:
|
||||
key: your_api_key
|
||||
timeout: 30
|
||||
|
||||
database:
|
||||
url: postgresql://user:pass@localhost/dbname
|
||||
pool_size: 5
|
||||
\`\`\`
|
||||
|
||||
## API Documentation
|
||||
|
||||
### Main Classes
|
||||
|
||||
#### `SomeClass`
|
||||
|
||||
Description of the class.
|
||||
|
||||
\`\`\`python
|
||||
from project_name import SomeClass
|
||||
|
||||
instance = SomeClass(param="value")
|
||||
result = instance.method()
|
||||
\`\`\`
|
||||
|
||||
**Parameters:**
|
||||
- `param` (str): Description of parameter
|
||||
|
||||
**Returns:**
|
||||
- `str`: Description of return value
|
||||
|
||||
### Functions
|
||||
|
||||
#### `main_function()`
|
||||
|
||||
Description of the function.
|
||||
|
||||
\`\`\`python
|
||||
from project_name import main_function
|
||||
|
||||
result = main_function()
|
||||
\`\`\`
|
||||
|
||||
## API Endpoints (if applicable)
|
||||
|
||||
### Start the Server
|
||||
|
||||
\`\`\`bash
|
||||
uv run uvicorn project_name.api.main:app --reload
|
||||
\`\`\`
|
||||
|
||||
### Endpoints
|
||||
|
||||
#### GET `/api/items`
|
||||
|
||||
Get all items.
|
||||
|
||||
**Response:**
|
||||
\`\`\`json
|
||||
{
|
||||
"items": [
|
||||
{"id": 1, "name": "Item 1"},
|
||||
{"id": 2, "name": "Item 2"}
|
||||
]
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
#### POST `/api/items`
|
||||
|
||||
Create a new item.
|
||||
|
||||
**Request Body:**
|
||||
\`\`\`json
|
||||
{
|
||||
"name": "New Item"
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
**Response:**
|
||||
\`\`\`json
|
||||
{
|
||||
"id": 3,
|
||||
"name": "New Item"
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions are welcome! Please follow these steps:
|
||||
|
||||
1. Fork the repository
|
||||
2. Create a feature branch (\`git checkout -b feature/amazing-feature\`)
|
||||
3. Make your changes
|
||||
4. Run tests and linting (\`uv run pytest && uv run ruff check .\`)
|
||||
5. Commit your changes (\`git commit -m 'Add amazing feature'\`)
|
||||
6. Push to the branch (\`git push origin feature/amazing-feature\`)
|
||||
7. Open a Pull Request
|
||||
|
||||
### Code Style
|
||||
|
||||
- Follow PEP 8 guidelines
|
||||
- Use type hints for all functions
|
||||
- Write docstrings for all public APIs
|
||||
- Maintain test coverage above 80%
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
||||
|
||||
## Authors
|
||||
|
||||
- Your Name - [@yourhandle](https://github.com/yourhandle)
|
||||
|
||||
## Acknowledgments
|
||||
|
||||
- Library or resource that inspired this project
|
||||
- Contributors who helped
|
||||
- Any other acknowledgments
|
||||
|
||||
## Changelog
|
||||
|
||||
### [0.1.0] - 2024-01-01
|
||||
|
||||
#### Added
|
||||
- Initial release
|
||||
- Basic functionality
|
||||
|
||||
#### Changed
|
||||
- Nothing yet
|
||||
|
||||
#### Fixed
|
||||
- Nothing yet
|
||||
|
||||
## Support
|
||||
|
||||
For support, email support@example.com or open an issue on GitHub.
|
||||
|
||||
## Links
|
||||
|
||||
- [Documentation](https://project-name.readthedocs.io)
|
||||
- [Issue Tracker](https://github.com/username/project-name/issues)
|
||||
- [Changelog](CHANGELOG.md)
|
||||
```
|
||||
|
||||
## Sections Explained
|
||||
|
||||
1. **Title & Description**: Clear project name and one-line summary
|
||||
2. **Overview**: More detailed description of purpose and features
|
||||
3. **Installation**: Step-by-step setup instructions
|
||||
4. **Quick Start**: Minimal example to get started quickly
|
||||
5. **Usage**: Detailed usage examples (CLI and library)
|
||||
6. **Development**: Instructions for contributors
|
||||
7. **Project Structure**: Overview of codebase organization
|
||||
8. **Configuration**: How to configure the application
|
||||
9. **API Documentation**: Documentation of public API
|
||||
10. **Contributing**: Guidelines for contributions
|
||||
11. **License & Authors**: Legal and attribution information
|
||||
12. **Support**: How to get help
|
||||
|
||||
## Tips for Good READMEs
|
||||
|
||||
- **Keep it concise**: Users should understand the project in 30 seconds
|
||||
- **Working examples**: All code examples should be copy-paste ready
|
||||
- **Clear installation**: Step-by-step instructions that actually work
|
||||
- **Visual aids**: Consider adding screenshots, diagrams, or GIFs
|
||||
- **Badges**: Add CI status, coverage, and version badges
|
||||
- **Update regularly**: Keep it in sync with the actual codebase
|
||||
Reference in New Issue
Block a user