From 54de1ea8e1cc7111ec53880bc9d8e1f4c22a897b Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 25 Oct 2025 19:29:57 +0000 Subject: [PATCH] docs: Add installation guide and quick test script MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- INSTALLATION_GUIDE.md | 287 +++++++++++++++++++++++++++++++++++++++++ examples/quick_test.py | 151 ++++++++++++++++++++++ 2 files changed, 438 insertions(+) create mode 100644 INSTALLATION_GUIDE.md create mode 100755 examples/quick_test.py diff --git a/INSTALLATION_GUIDE.md b/INSTALLATION_GUIDE.md new file mode 100644 index 0000000..408e1cb --- /dev/null +++ b/INSTALLATION_GUIDE.md @@ -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) diff --git a/examples/quick_test.py b/examples/quick_test.py new file mode 100755 index 0000000..2673dad --- /dev/null +++ b/examples/quick_test.py @@ -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())