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)
|
||||
151
examples/quick_test.py
Executable file
151
examples/quick_test.py
Executable file
@@ -0,0 +1,151 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Quick test script to verify py-wikijs installation and connectivity.
|
||||
|
||||
This script helps you verify that py-wikijs is installed correctly and can
|
||||
connect to your Wiki.js instance.
|
||||
|
||||
Usage:
|
||||
python quick_test.py
|
||||
|
||||
Or set environment variables:
|
||||
export WIKIJS_URL="https://your-wiki.example.com"
|
||||
export WIKIJS_API_KEY="your-api-key-here"
|
||||
python quick_test.py
|
||||
"""
|
||||
|
||||
import os
|
||||
import sys
|
||||
from typing import Optional
|
||||
|
||||
|
||||
def test_import() -> bool:
|
||||
"""Test that py-wikijs can be imported."""
|
||||
print("=" * 60)
|
||||
print("TEST 1: Package Import")
|
||||
print("=" * 60)
|
||||
try:
|
||||
from wikijs import WikiJSClient, __version__
|
||||
|
||||
print(f"✅ Successfully imported py-wikijs v{__version__}")
|
||||
return True
|
||||
except ImportError as e:
|
||||
print(f"❌ Failed to import py-wikijs: {e}")
|
||||
print("\nInstall with: pip install git+https://github.com/l3ocho/py-wikijs.git@v0.1.0")
|
||||
return False
|
||||
|
||||
|
||||
def test_connectivity(url: Optional[str] = None, api_key: Optional[str] = None) -> bool:
|
||||
"""Test connectivity to Wiki.js instance."""
|
||||
print("\n" + "=" * 60)
|
||||
print("TEST 2: Wiki.js Connectivity")
|
||||
print("=" * 60)
|
||||
|
||||
# Get credentials
|
||||
url = url or os.getenv("WIKIJS_URL")
|
||||
api_key = api_key or os.getenv("WIKIJS_API_KEY")
|
||||
|
||||
if not url or not api_key:
|
||||
print("⚠️ Skipping connectivity test - credentials not provided")
|
||||
print("\nTo test connectivity, set environment variables:")
|
||||
print(" export WIKIJS_URL='https://your-wiki.example.com'")
|
||||
print(" export WIKIJS_API_KEY='your-api-key-here'")
|
||||
return False
|
||||
|
||||
try:
|
||||
from wikijs import WikiJSClient
|
||||
|
||||
print(f"🔗 Connecting to: {url}")
|
||||
client = WikiJSClient(url=url, auth=api_key)
|
||||
|
||||
# Try to list pages
|
||||
pages = client.pages.list()
|
||||
print(f"✅ Successfully connected to Wiki.js")
|
||||
print(f"✅ Found {len(pages)} page(s)")
|
||||
|
||||
# Show first page if available
|
||||
if pages:
|
||||
first_page = pages[0]
|
||||
print(f"\nFirst page:")
|
||||
print(f" - ID: {first_page.id}")
|
||||
print(f" - Title: {first_page.title}")
|
||||
print(f" - Path: {first_page.path}")
|
||||
|
||||
return True
|
||||
|
||||
except Exception as e:
|
||||
print(f"❌ Failed to connect: {e}")
|
||||
print("\nPlease verify:")
|
||||
print(" 1. Wiki.js URL is correct and accessible")
|
||||
print(" 2. API key is valid and has necessary permissions")
|
||||
print(" 3. Wiki.js version is 2.2 or higher (not 3.x)")
|
||||
return False
|
||||
|
||||
|
||||
def test_features() -> bool:
|
||||
"""Test that key features are available."""
|
||||
print("\n" + "=" * 60)
|
||||
print("TEST 3: Feature Availability")
|
||||
print("=" * 60)
|
||||
|
||||
try:
|
||||
from wikijs import (
|
||||
APIKeyAuth,
|
||||
AuthenticationError,
|
||||
JWTAuth,
|
||||
Page,
|
||||
PageCreate,
|
||||
WikiJSClient,
|
||||
)
|
||||
|
||||
print("✅ Core client: WikiJSClient")
|
||||
print("✅ Authentication: APIKeyAuth, JWTAuth")
|
||||
print("✅ Models: Page, PageCreate")
|
||||
print("✅ Exceptions: AuthenticationError")
|
||||
print("✅ All core features available")
|
||||
return True
|
||||
|
||||
except ImportError as e:
|
||||
print(f"❌ Missing features: {e}")
|
||||
return False
|
||||
|
||||
|
||||
def main() -> int:
|
||||
"""Run all tests."""
|
||||
print("\n🧪 py-wikijs Installation & Connectivity Test")
|
||||
print("=" * 60)
|
||||
|
||||
results = []
|
||||
|
||||
# Test 1: Import
|
||||
results.append(test_import())
|
||||
|
||||
# Test 2: Connectivity (optional)
|
||||
results.append(test_connectivity())
|
||||
|
||||
# Test 3: Features
|
||||
results.append(test_features())
|
||||
|
||||
# Summary
|
||||
print("\n" + "=" * 60)
|
||||
print("TEST SUMMARY")
|
||||
print("=" * 60)
|
||||
|
||||
passed = sum(results)
|
||||
total = len(results)
|
||||
|
||||
print(f"Tests passed: {passed}/{total}")
|
||||
|
||||
if all(results):
|
||||
print("\n🎉 All tests passed! py-wikijs is ready to use.")
|
||||
return 0
|
||||
elif results[0] and results[2]: # Import and features work
|
||||
print("\n✅ Installation verified!")
|
||||
print("ℹ️ Set WIKIJS_URL and WIKIJS_API_KEY to test connectivity")
|
||||
return 0
|
||||
else:
|
||||
print("\n❌ Some tests failed. Please check the errors above.")
|
||||
return 1
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
Reference in New Issue
Block a user