py-wikijs/INSTALLATION_GUIDE.md

# 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)