Lukas
36acd3999e
- Fix search API key extraction from link slugs - All 1006 tests pass - All 19 performance tests pass - Manual end-to-end testing verified - Key lookup performance: O(1) ~0.11μs per lookup Phase 9 tasks completed: - Task 9.1: Full test suite validation - Task 9.2: Manual end-to-end testing - Task 9.3: Performance testing All identifier standardization phases (1-9) now complete.
346 lines
8.5 KiB
Markdown
346 lines
8.5 KiB
Markdown
# Aniworld Documentation
|
|
|
|
Complete documentation for the Aniworld Download Manager application.
|
|
|
|
## Quick Start
|
|
|
|
- **New Users**: Start with [User Guide](./user_guide.md)
|
|
- **Developers**: Check [API Reference](./api_reference.md)
|
|
- **System Admins**: See [Deployment Guide](./deployment.md)
|
|
- **Interactive Docs**: Visit `http://localhost:8000/api/docs`
|
|
|
|
## Documentation Structure
|
|
|
|
### 📖 User Guide (`user_guide.md`)
|
|
|
|
Complete guide for end users covering:
|
|
|
|
- Installation instructions
|
|
- Initial setup and configuration
|
|
- User interface walkthrough
|
|
- Managing anime library
|
|
- Download queue management
|
|
- Configuration and settings
|
|
- Troubleshooting common issues
|
|
- Keyboard shortcuts
|
|
- Frequently asked questions (FAQ)
|
|
|
|
**Best for**: Anyone using the Aniworld application
|
|
|
|
### 🔌 API Reference (`api_reference.md`)
|
|
|
|
Detailed API documentation including:
|
|
|
|
- Authentication and authorization
|
|
- Error handling and status codes
|
|
- All REST endpoints with examples
|
|
- WebSocket real-time updates
|
|
- Request/response formats
|
|
- Rate limiting and pagination
|
|
- Complete workflow examples
|
|
- API changelog
|
|
|
|
**Best for**: Developers integrating with the API
|
|
|
|
### 🚀 Deployment Guide (`deployment.md`)
|
|
|
|
Production deployment instructions covering:
|
|
|
|
- System requirements
|
|
- Pre-deployment checklist
|
|
- Local development setup
|
|
- Production deployment steps
|
|
- Docker and Docker Compose setup
|
|
- Nginx reverse proxy configuration
|
|
- SSL/TLS certificate setup
|
|
- Database configuration (SQLite and PostgreSQL)
|
|
- Security best practices
|
|
- Monitoring and maintenance
|
|
- Troubleshooting deployment issues
|
|
|
|
**Best for**: System administrators and DevOps engineers
|
|
|
|
## Key Features Documented
|
|
|
|
### Authentication
|
|
|
|
- Master password setup and login
|
|
- JWT token management
|
|
- Session handling
|
|
- Security best practices
|
|
|
|
### Configuration Management
|
|
|
|
- Application settings
|
|
- Directory configuration
|
|
- Backup and restore functionality
|
|
- Environment variables
|
|
|
|
### Anime Management
|
|
|
|
- Browsing anime library
|
|
- Adding new anime
|
|
- Managing episodes
|
|
- Search functionality
|
|
|
|
### Download Management
|
|
|
|
- Queue operations
|
|
- Priority management
|
|
- Progress tracking
|
|
- Error recovery
|
|
|
|
### Real-time Features
|
|
|
|
- WebSocket connections
|
|
- Live download updates
|
|
- Status notifications
|
|
- Error alerts
|
|
|
|
## Series Identifier Convention
|
|
|
|
### Understanding Series Identifiers
|
|
|
|
The application uses two identifiers for anime series:
|
|
|
|
| Identifier | Purpose | Example | Used For |
|
|
| ---------- | ------------------------ | -------------------------- | ---------------- |
|
|
| `key` | **Primary identifier** | `"attack-on-titan"` | All API lookups |
|
|
| `folder` | Filesystem metadata only | `"Attack on Titan (2013)"` | Display purposes |
|
|
|
|
### Key Format
|
|
|
|
- Lowercase letters and numbers only
|
|
- Words separated by hyphens (`-`)
|
|
- No spaces, underscores, or uppercase letters
|
|
- Examples: `"one-piece"`, `"86-eighty-six"`, `"re-zero"`
|
|
|
|
### Usage Guidelines
|
|
|
|
```python
|
|
# ✅ Correct: Use 'key' for API operations
|
|
GET /api/anime/attack-on-titan
|
|
POST /api/queue/add {"serie_id": "attack-on-titan", ...}
|
|
|
|
# ❌ Deprecated: Folder-based lookups (backward compatibility only)
|
|
GET /api/anime/Attack%20on%20Titan%20(2013) # Will work but deprecated
|
|
```
|
|
|
|
### Backward Compatibility
|
|
|
|
For existing integrations, folder-based lookups are still supported but deprecated:
|
|
|
|
- API endpoints check `key` first, then fall back to `folder`
|
|
- New code should always use `key` as the identifier
|
|
- Deprecation warnings will be added in future versions
|
|
|
|
## Documentation Examples
|
|
|
|
### API Usage Example
|
|
|
|
```bash
|
|
# Setup
|
|
curl -X POST http://localhost:8000/api/auth/setup \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"master_password": "secure_pass"}'
|
|
|
|
# Login
|
|
TOKEN=$(curl -X POST http://localhost:8000/api/auth/login \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"password": "secure_pass"}' | jq -r '.token')
|
|
|
|
# List anime
|
|
curl http://localhost:8000/api/v1/anime \
|
|
-H "Authorization: Bearer $TOKEN"
|
|
```
|
|
|
|
### Deployment Example
|
|
|
|
```bash
|
|
# Clone and setup
|
|
git clone https://github.com/your-repo/aniworld.git
|
|
cd aniworld
|
|
python3.10 -m venv venv
|
|
source venv/bin/activate
|
|
pip install -r requirements.txt
|
|
|
|
# Run application
|
|
python -m uvicorn src.server.fastapi_app:app --host 127.0.0.1 --port 8000
|
|
```
|
|
|
|
## Interactive Documentation
|
|
|
|
Access interactive API documentation at:
|
|
|
|
- **Swagger UI**: `http://localhost:8000/api/docs`
|
|
- **ReDoc**: `http://localhost:8000/api/redoc`
|
|
- **OpenAPI JSON**: `http://localhost:8000/openapi.json`
|
|
|
|
These provide:
|
|
|
|
- Interactive API explorer
|
|
- Try-it-out functionality
|
|
- Request/response examples
|
|
- Schema validation
|
|
|
|
## Common Tasks
|
|
|
|
### I want to...
|
|
|
|
**Use the application**
|
|
→ Read [User Guide](./user_guide.md) → Getting Started section
|
|
|
|
**Set up on my computer**
|
|
→ Read [User Guide](./user_guide.md) → Installation section
|
|
|
|
**Deploy to production**
|
|
→ Read [Deployment Guide](./deployment.md) → Production Deployment
|
|
|
|
**Use the API**
|
|
→ Read [API Reference](./api_reference.md) → API Endpoints section
|
|
|
|
**Troubleshoot problems**
|
|
→ Read [User Guide](./user_guide.md) → Troubleshooting section
|
|
|
|
**Set up with Docker**
|
|
→ Read [Deployment Guide](./deployment.md) → Docker Deployment
|
|
|
|
**Configure backup/restore**
|
|
→ Read [User Guide](./user_guide.md) → Configuration section
|
|
|
|
**Debug API issues**
|
|
→ Check [API Reference](./api_reference.md) → Error Handling section
|
|
|
|
## Documentation Standards
|
|
|
|
All documentation follows these standards:
|
|
|
|
### Structure
|
|
|
|
- Clear table of contents
|
|
- Logical section ordering
|
|
- Cross-references to related topics
|
|
- Code examples where appropriate
|
|
|
|
### Style
|
|
|
|
- Plain, accessible language
|
|
- Step-by-step instructions
|
|
- Visual formatting (code blocks, tables, lists)
|
|
- Examples for common scenarios
|
|
|
|
### Completeness
|
|
|
|
- All major features covered
|
|
- Edge cases documented
|
|
- Troubleshooting guidance
|
|
- FAQ section included
|
|
|
|
### Maintenance
|
|
|
|
- Version number tracking
|
|
- Last updated timestamp
|
|
- Changelog for updates
|
|
- Broken link checking
|
|
|
|
## Help & Support
|
|
|
|
### Getting Help
|
|
|
|
1. **Check Documentation First**
|
|
|
|
- Search in relevant guide
|
|
- Check FAQ section
|
|
- Look for similar examples
|
|
|
|
2. **Check Logs**
|
|
|
|
- Application logs in `/logs/`
|
|
- Browser console (F12)
|
|
- System logs
|
|
|
|
3. **Try Troubleshooting**
|
|
|
|
- Follow troubleshooting steps in user guide
|
|
- Check known issues section
|
|
- Verify system requirements
|
|
|
|
4. **Get Community Help**
|
|
|
|
- GitHub Issues
|
|
- Discussion Forums
|
|
- Community Discord
|
|
|
|
5. **Report Issues**
|
|
- File GitHub issue
|
|
- Include logs and error messages
|
|
- Describe reproduction steps
|
|
- Specify system details
|
|
|
|
### Feedback
|
|
|
|
We welcome feedback on documentation:
|
|
|
|
- Unclear sections
|
|
- Missing information
|
|
- Incorrect instructions
|
|
- Outdated content
|
|
- Suggest improvements
|
|
|
|
File documentation issues on GitHub with label `documentation`.
|
|
|
|
## Contributing to Documentation
|
|
|
|
Documentation improvements are welcome! To contribute:
|
|
|
|
1. Fork the repository
|
|
2. Edit documentation files
|
|
3. Test changes locally
|
|
4. Submit pull request
|
|
5. Include summary of changes
|
|
|
|
See `CONTRIBUTING.md` for guidelines.
|
|
|
|
## Documentation Map
|
|
|
|
```
|
|
docs/
|
|
├── README.md # This file
|
|
├── user_guide.md # End-user documentation
|
|
├── api_reference.md # API documentation
|
|
├── deployment.md # Deployment instructions
|
|
└── CONTRIBUTING.md # Contribution guidelines
|
|
```
|
|
|
|
## Related Resources
|
|
|
|
- **Source Code**: GitHub repository
|
|
- **Interactive API**: `http://localhost:8000/api/docs`
|
|
- **Issue Tracker**: GitHub Issues
|
|
- **Releases**: GitHub Releases
|
|
- **License**: See LICENSE file
|
|
|
|
## Document Info
|
|
|
|
- **Last Updated**: November 28, 2025
|
|
- **Version**: 2.0.0
|
|
- **Status**: Production Ready
|
|
- **Maintainers**: Development Team
|
|
|
|
---
|
|
|
|
## Quick Links
|
|
|
|
| Resource | Link |
|
|
| ------------------ | -------------------------------------------- |
|
|
| User Guide | [user_guide.md](./user_guide.md) |
|
|
| API Reference | [api_reference.md](./api_reference.md) |
|
|
| Deployment Guide | [deployment.md](./deployment.md) |
|
|
| Swagger UI | http://localhost:8000/api/docs |
|
|
| GitHub Issues | https://github.com/your-repo/aniworld/issues |
|
|
| Project Repository | https://github.com/your-repo/aniworld |
|
|
|
|
---
|
|
|
|
**For Questions**: Check relevant guide first, then file GitHub issue with details.
|