schihei
5e891ef461
This commit adds extensive documentation to the Mistral OCR CLI project: - Add API.md with detailed API response format documentation - Add CHANGELOG.md to track version changes - Add CONTRIBUTING.md with guidelines for contributors - Enhance README.md with more detailed usage examples and troubleshooting - Add proper docstrings to all Python modules and functions - Update requirements.txt with development dependencies - Improve setup.py with better metadata These changes make the project more accessible to users and contributors.
172 lines
4.3 KiB
Markdown
172 lines
4.3 KiB
Markdown
# Contributing to Mistral OCR CLI
|
|
|
|
Thank you for your interest in contributing to Mistral OCR CLI! This document provides guidelines and instructions for contributing to this project.
|
|
|
|
## Table of Contents
|
|
|
|
- [Contributing to Mistral OCR CLI](#contributing-to-mistral-ocr-cli)
|
|
- [Table of Contents](#table-of-contents)
|
|
- [Code of Conduct](#code-of-conduct)
|
|
- [Getting Started](#getting-started)
|
|
- [Development Environment Setup](#development-environment-setup)
|
|
- [Project Structure](#project-structure)
|
|
- [Development Workflow](#development-workflow)
|
|
- [Creating a Feature](#creating-a-feature)
|
|
- [Testing](#testing)
|
|
- [Documentation](#documentation)
|
|
- [Pull Request Process](#pull-request-process)
|
|
- [Coding Standards](#coding-standards)
|
|
- [Release Process](#release-process)
|
|
|
|
## Code of Conduct
|
|
|
|
Please be respectful and considerate of others when contributing to this project. We aim to foster an inclusive and welcoming community.
|
|
|
|
## Getting Started
|
|
|
|
### Development Environment Setup
|
|
|
|
1. **Fork and clone the repository**:
|
|
```bash
|
|
git clone https://github.com/yourusername/mistral-ocr-python.git
|
|
cd mistral-ocr-python
|
|
```
|
|
|
|
2. **Create a virtual environment**:
|
|
```bash
|
|
python -m venv venv
|
|
source venv/bin/activate # On Windows: venv\Scripts\activate
|
|
```
|
|
|
|
3. **Install the package in development mode**:
|
|
```bash
|
|
pip install -e .
|
|
```
|
|
|
|
4. **Install development dependencies**:
|
|
```bash
|
|
pip install pytest pytest-cov black flake8
|
|
```
|
|
|
|
### Project Structure
|
|
|
|
```
|
|
mistral-ocr-python/
|
|
├── mistral_ocr/ # Main package
|
|
│ ├── __init__.py
|
|
│ ├── __main__.py # CLI entry point
|
|
│ ├── client.py # Mistral API client
|
|
│ └── commands/ # Command implementations
|
|
│ ├── __init__.py
|
|
│ ├── convert.py # Convert command
|
|
│ ├── markdown.py # Markdown command
|
|
│ ├── process.py # Process command
|
|
│ └── version.py # Version command
|
|
├── tests/ # Test directory
|
|
├── .gitignore
|
|
├── README.md
|
|
├── CONTRIBUTING.md
|
|
├── LICENSE
|
|
├── requirements.txt
|
|
├── setup.py
|
|
└── build.sh
|
|
```
|
|
|
|
## Development Workflow
|
|
|
|
### Creating a Feature
|
|
|
|
1. **Create a new branch**:
|
|
```bash
|
|
git checkout -b feature/your-feature-name
|
|
```
|
|
|
|
2. **Make your changes**:
|
|
- Implement your feature or fix
|
|
- Add or update tests as necessary
|
|
- Update documentation to reflect your changes
|
|
|
|
3. **Commit your changes**:
|
|
```bash
|
|
git add .
|
|
git commit -m "Add feature: your feature description"
|
|
```
|
|
|
|
### Testing
|
|
|
|
We use pytest for testing. To run the tests:
|
|
|
|
```bash
|
|
python -m pytest
|
|
```
|
|
|
|
For coverage report:
|
|
|
|
```bash
|
|
python -m pytest --cov=mistral_ocr
|
|
```
|
|
|
|
Please ensure that your code is well-tested and that all tests pass before submitting a pull request.
|
|
|
|
### Documentation
|
|
|
|
- Update the README.md if your changes affect the usage of the tool
|
|
- Add docstrings to your code following the Google style guide
|
|
- Update or add examples if necessary
|
|
|
|
## Pull Request Process
|
|
|
|
1. **Push your changes to your fork**:
|
|
```bash
|
|
git push origin feature/your-feature-name
|
|
```
|
|
|
|
2. **Create a pull request** from your fork to the main repository
|
|
|
|
3. **Describe your changes** in the pull request:
|
|
- What does this PR add or fix?
|
|
- Any breaking changes?
|
|
- Any dependencies added?
|
|
|
|
4. **Address review comments** if any are provided
|
|
|
|
5. **Your PR will be merged** once it's approved
|
|
|
|
## Coding Standards
|
|
|
|
We follow PEP 8 and use Black for code formatting:
|
|
|
|
```bash
|
|
black mistral_ocr
|
|
```
|
|
|
|
For linting:
|
|
|
|
```bash
|
|
flake8 mistral_ocr
|
|
```
|
|
|
|
General guidelines:
|
|
|
|
- Use descriptive variable and function names
|
|
- Add type hints to function signatures
|
|
- Write docstrings for all functions, classes, and modules
|
|
- Keep functions small and focused on a single task
|
|
- Use comments to explain complex logic
|
|
|
|
## Release Process
|
|
|
|
Releases are managed by the project maintainers. If you'd like to propose a release:
|
|
|
|
1. Update the version number in:
|
|
- `mistral_ocr/commands/version.py`
|
|
- `setup.py`
|
|
|
|
2. Update the CHANGELOG.md with the changes in the new version
|
|
|
|
3. Create a pull request with these changes
|
|
|
|
4. Once merged, the maintainers will create a new release tag
|
|
|
|
Thank you for contributing to Mistral OCR CLI!
|