docs: Add installation guide and quick test script
Added comprehensive documentation to help users install and test py-wikijs in their projects before public release. Changes: - INSTALLATION_GUIDE.md: Complete guide for all installation methods * GitHub installation (recommended for now) * requirements.txt integration * pyproject.toml integration * Local development setup * Usage examples and troubleshooting - examples/quick_test.py: Verification script * Tests package import * Tests Wiki.js connectivity (optional) * Validates feature availability * Provides clear diagnostic output This prepares the package for testing in external projects before making the repository public. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Claude
287
INSTALLATION_GUIDE.md
Normal file
287
INSTALLATION_GUIDE.md
Normal file
@@ -0,0 +1,287 @@
|
||||
# Installation Guide - py-wikijs
|
||||
|
||||
**Quick reference for installing and using py-wikijs in your projects**
|
||||
|
||||
---
|
||||
|
||||
## 📦 Installation Methods
|
||||
|
||||
### **Method 1: Install from GitHub (Recommended for now)**
|
||||
|
||||
Since this package is not yet on PyPI, install directly from GitHub:
|
||||
|
||||
```bash
|
||||
# Install the latest release (v0.1.0)
|
||||
pip install git+https://github.com/l3ocho/py-wikijs.git@v0.1.0
|
||||
|
||||
# Or install from a specific branch
|
||||
pip install git+https://github.com/l3ocho/py-wikijs.git@main
|
||||
|
||||
# Or install from the current development branch
|
||||
pip install git+https://github.com/l3ocho/py-wikijs.git@claude/test-tool-integration-011CUUU3JXwm8n8waD6UYeea
|
||||
```
|
||||
|
||||
### **Method 2: Install in requirements.txt**
|
||||
|
||||
Add to your `requirements.txt`:
|
||||
|
||||
```text
|
||||
# Install specific version tag
|
||||
git+https://github.com/l3ocho/py-wikijs.git@v0.1.0
|
||||
|
||||
# Or install from main branch
|
||||
git+https://github.com/l3ocho/py-wikijs.git@main
|
||||
```
|
||||
|
||||
Then install:
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### **Method 3: Install in pyproject.toml (Poetry/Modern Python)**
|
||||
|
||||
Add to your `pyproject.toml`:
|
||||
|
||||
```toml
|
||||
[project.dependencies]
|
||||
py-wikijs = { git = "https://github.com/l3ocho/py-wikijs.git", tag = "v0.1.0" }
|
||||
```
|
||||
|
||||
Or for Poetry:
|
||||
```toml
|
||||
[tool.poetry.dependencies]
|
||||
py-wikijs = { git = "https://github.com/l3ocho/py-wikijs.git", tag = "v0.1.0" }
|
||||
```
|
||||
|
||||
### **Method 4: Local Development (Editable Install)**
|
||||
|
||||
If you're developing both projects simultaneously:
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/l3ocho/py-wikijs.git
|
||||
cd py-wikijs
|
||||
|
||||
# Install in editable mode
|
||||
pip install -e .
|
||||
|
||||
# Or install with development dependencies
|
||||
pip install -e ".[dev]"
|
||||
|
||||
# Or install with async support
|
||||
pip install -e ".[async]"
|
||||
```
|
||||
|
||||
Then in your other project, the package will automatically reflect changes.
|
||||
|
||||
---
|
||||
|
||||
## ✅ Verification
|
||||
|
||||
After installation, verify it works:
|
||||
|
||||
```bash
|
||||
# Check installation
|
||||
python -c "from wikijs import WikiJSClient, __version__; print(f'py-wikijs v{__version__} installed successfully!')"
|
||||
|
||||
# Should output: py-wikijs v0.1.0 installed successfully!
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Basic Usage in Your Project
|
||||
|
||||
### **Simple Example**
|
||||
|
||||
Create a file `test_wikijs.py`:
|
||||
|
||||
```python
|
||||
from wikijs import WikiJSClient
|
||||
|
||||
# Initialize client with API key
|
||||
client = WikiJSClient(
|
||||
url='https://your-wiki.example.com',
|
||||
auth='your-api-key-here'
|
||||
)
|
||||
|
||||
# List all pages
|
||||
pages = client.pages.list()
|
||||
print(f"Found {len(pages)} pages")
|
||||
|
||||
# Get a specific page
|
||||
page = client.pages.get(page_id=1)
|
||||
print(f"Page title: {page.title}")
|
||||
```
|
||||
|
||||
### **With Environment Variables (Recommended)**
|
||||
|
||||
Create `.env` file:
|
||||
```env
|
||||
WIKIJS_URL=https://your-wiki.example.com
|
||||
WIKIJS_API_KEY=your-api-key-here
|
||||
```
|
||||
|
||||
In your code:
|
||||
```python
|
||||
import os
|
||||
from wikijs import WikiJSClient
|
||||
|
||||
# Load from environment
|
||||
client = WikiJSClient(
|
||||
url=os.getenv('WIKIJS_URL'),
|
||||
auth=os.getenv('WIKIJS_API_KEY')
|
||||
)
|
||||
```
|
||||
|
||||
### **Advanced Features**
|
||||
|
||||
```python
|
||||
from wikijs import WikiJSClient
|
||||
import logging
|
||||
|
||||
# Enable debug logging
|
||||
client = WikiJSClient(
|
||||
url='https://wiki.example.com',
|
||||
auth='your-api-key',
|
||||
log_level=logging.DEBUG,
|
||||
rate_limit=10.0, # 10 requests/second
|
||||
timeout=30.0 # 30 second timeout
|
||||
)
|
||||
|
||||
# Create a new page
|
||||
from wikijs.models import PageCreate
|
||||
|
||||
new_page = client.pages.create(PageCreate(
|
||||
title="My New Page",
|
||||
path="documentation/my-new-page",
|
||||
content="# Welcome\n\nThis is my new page!",
|
||||
description="A new documentation page",
|
||||
is_published=True,
|
||||
is_private=False,
|
||||
locale="en",
|
||||
tags=["documentation", "tutorial"]
|
||||
))
|
||||
|
||||
print(f"Created page: {new_page.title} (ID: {new_page.id})")
|
||||
|
||||
# Get metrics
|
||||
metrics = client.get_metrics()
|
||||
print(f"Total requests: {metrics['total_requests']}")
|
||||
print(f"Error rate: {metrics['error_rate']:.2f}%")
|
||||
```
|
||||
|
||||
### **Async Usage (Future - v0.2.0)**
|
||||
|
||||
When async support is released:
|
||||
|
||||
```python
|
||||
from wikijs.aio import AsyncWikiJSClient
|
||||
|
||||
async def main():
|
||||
async with AsyncWikiJSClient(
|
||||
url='https://wiki.example.com',
|
||||
auth='your-api-key'
|
||||
) as client:
|
||||
pages = await client.pages.list()
|
||||
print(f"Found {len(pages)} pages")
|
||||
|
||||
# Run with asyncio
|
||||
import asyncio
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Dependencies
|
||||
|
||||
**Required:**
|
||||
- Python >= 3.8
|
||||
- requests >= 2.28.0
|
||||
- pydantic >= 1.10.0
|
||||
- typing-extensions >= 4.0.0
|
||||
|
||||
**Optional:**
|
||||
- aiohttp >= 3.8.0 (for async support - coming in v0.2.0)
|
||||
- click >= 8.0.0 (for CLI tools - future)
|
||||
- rich >= 12.0.0 (for rich output - future)
|
||||
|
||||
---
|
||||
|
||||
## 📚 Documentation
|
||||
|
||||
- **API Reference**: [docs/api_reference.md](docs/api_reference.md)
|
||||
- **User Guide**: [docs/user_guide.md](docs/user_guide.md)
|
||||
- **Examples**: [examples/](examples/)
|
||||
- **Compatibility**: [docs/compatibility.md](docs/compatibility.md)
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Important Notes
|
||||
|
||||
### **Before Going Public:**
|
||||
|
||||
1. ✅ **Version Tag Created**: v0.1.0 is now tagged
|
||||
2. ✅ **Package Structure**: Ready for installation
|
||||
3. ⏳ **PyPI Publishing**: Not yet published (GitHub-only for now)
|
||||
4. ⏳ **GitHub Release**: Consider creating a GitHub Release page
|
||||
|
||||
### **Production Checklist:**
|
||||
|
||||
- [ ] Set up proper Wiki.js instance with API access
|
||||
- [ ] Store API keys securely (use environment variables)
|
||||
- [ ] Enable appropriate logging for production
|
||||
- [ ] Set rate limits to respect your Wiki.js server
|
||||
- [ ] Monitor metrics for performance issues
|
||||
- [ ] Review security best practices in [docs/SECURITY.md](docs/SECURITY.md)
|
||||
|
||||
### **Wiki.js Requirements:**
|
||||
|
||||
- **Supported Versions**: Wiki.js 2.2 through 2.5.x
|
||||
- **Not Supported**: Wiki.js 3.x (different API schema)
|
||||
- **API Access**: Requires valid API key with appropriate permissions
|
||||
|
||||
---
|
||||
|
||||
## 🐛 Troubleshooting
|
||||
|
||||
### **Import Error**
|
||||
```python
|
||||
ModuleNotFoundError: No module named 'wikijs'
|
||||
```
|
||||
**Solution**: Ensure package is installed: `pip install git+https://github.com/l3ocho/py-wikijs.git@v0.1.0`
|
||||
|
||||
### **Authentication Error**
|
||||
```python
|
||||
wikijs.exceptions.AuthenticationError: Invalid API key
|
||||
```
|
||||
**Solution**: Check your API key is correct and has necessary permissions in Wiki.js
|
||||
|
||||
### **Connection Error**
|
||||
```python
|
||||
wikijs.exceptions.ConnectionError: Failed to connect to Wiki.js
|
||||
```
|
||||
**Solution**: Verify Wiki.js URL is correct and accessible from your network
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Next Steps
|
||||
|
||||
1. **Install the package** using one of the methods above
|
||||
2. **Get your Wiki.js API key** from your Wiki.js admin panel
|
||||
3. **Test basic connectivity** with a simple script
|
||||
4. **Explore examples** in the [examples/](examples/) directory
|
||||
5. **Read the documentation** for advanced features
|
||||
|
||||
---
|
||||
|
||||
## 📞 Support
|
||||
|
||||
- **Issues**: https://github.com/l3ocho/py-wikijs/issues
|
||||
- **Discussions**: https://github.com/l3ocho/py-wikijs/discussions
|
||||
- **Documentation**: https://github.com/l3ocho/py-wikijs/tree/main/docs
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-10-25
|
||||
**Package Version**: v0.1.0
|
||||
**Status**: Production Ready (MVP)
|
||||
Reference in New Issue
Block a user