ocs: add GitHub Pages site

Author: kacigaya

.github/workflows/docs.yml

@@ -0,0 +1,41 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Install docs dependencies
+        run: python -m pip install -e ".[docs]"
+      - name: Build docs
+        run: mkdocs build --strict
+      - uses: actions/configure-pages@v5
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -8,6 +8,7 @@ __pycache__/
 htmlcov/
 dist/
 build/
+site/
 *.egg-info/
 .webskrap/
 test.py

README.md

@@ -11,6 +11,8 @@
 
 WebSkrap does not include CAPTCHA solving, login-wall bypassing, credential bypassing, or access-control circumvention. Use it only on targets you are allowed to access.
 
+Documentation: https://kacigaya.github.io/webskrap/
+
 ## Install
 
 ```bash

docs/api-reference.md

@@ -0,0 +1,23 @@
+# API Reference
+
+::: webskrap.WebSkrapClient
+
+::: webskrap.WebSkrapSession
+
+::: webskrap.BrowserProfile
+
+::: webskrap.SessionConfig
+
+::: webskrap.StealthConfig
+
+::: webskrap.ProxyConfig
+
+::: webskrap.ResourcePolicy
+
+::: webskrap.Viewport
+
+::: webskrap.FetchResult
+
+::: webskrap.get_profile
+
+::: webskrap.list_profiles

docs/assets/webskrap-logo.png

@@ -0,0 +1,44 @@
+# Development
+
+Clone the repository:
+
+```bash
+git clone https://github.com/kacigaya/webskrap.git
+cd webskrap
+```
+
+Install development dependencies:
+
+```bash
+pip install -e ".[dev,docs]"
+python -m playwright install chromium
+```
+
+Run tests and lint:
+
+```bash
+pytest -q
+ruff check .
+```
+
+Preview docs locally:
+
+```bash
+mkdocs serve
+```
+
+Build docs:
+
+```bash
+mkdocs build --strict
+```
+
+## Publishing Docs
+
+Docs are deployed by GitHub Actions from `main`.
+
+Repository settings must use:
+
+- Settings
+- Pages
+- Source: GitHub Actions

docs/development.md

@@ -0,0 +1,39 @@
+# Installation
+
+Install WebSkrap from PyPI:
+
+```bash
+pip install webskrap
+```
+
+Install Playwright's Chromium browser:
+
+```bash
+python -m playwright install chromium
+```
+
+Verify the installation:
+
+```bash
+webskrap doctor
+webskrap profiles
+```
+
+## Development Install
+
+For local development:
+
+```bash
+git clone https://github.com/kacigaya/webskrap.git
+cd webskrap
+pip install -e ".[dev,docs]"
+python -m playwright install chromium
+```
+
+Run checks:
+
+```bash
+pytest -q
+ruff check .
+mkdocs build --strict
+```

docs/getting-started/installation.md

@@ -0,0 +1,56 @@
+# Quickstart
+
+## One-Shot Fetch
+
+```python
+import asyncio
+
+from webskrap import WebSkrapClient
+
+
+async def main() -> None:
+    async with WebSkrapClient() as client:
+        result = await client.fetch("https://example.com")
+        print(result.status)
+        print(result.final_url)
+        print(result.title)
+        print(result.text[:200])
+
+
+asyncio.run(main())
+```
+
+## Keep A Headed Browser Open
+
+Use a session when you want the browser to remain open for inspection.
+
+```python
+import asyncio
+from pathlib import Path
+
+from webskrap import SessionConfig, WebSkrapClient
+
+
+async def main() -> None:
+    config = SessionConfig(
+        headless=False,
+        user_data_dir=Path(".webskrap/dev-session"),
+    )
+
+    async with WebSkrapClient() as client:
+        session = await client.session("dev", config=config)
+        page = await session.context.new_page()
+        await page.goto("https://example.com", wait_until="domcontentloaded")
+
+        input("Press Enter to close browser...")
+
+
+asyncio.run(main())
+```
+
+## CLI Fetch
+
+```bash
+webskrap fetch https://example.com
+webskrap fetch https://example.com --headed --screenshot example.png
+```

docs/getting-started/quickstart.md

@@ -0,0 +1,50 @@
+# WebSkrap
+
+WebSkrap is an async-first Python scraping framework built on Playwright.
+
+It provides coherent browser profiles, persistent browser sessions, resource routing, a CLI, and configurable browser hardening for data collection workflows that need realistic browser behavior.
+
+!!! warning "Usage boundary"
+    WebSkrap does not include CAPTCHA solving, login-wall bypassing, credential bypassing, or access-control circumvention. Use it only on targets you are allowed to access.
+
+## Install
+
+```bash
+pip install webskrap
+python -m playwright install chromium
+```
+
+## First Fetch
+
+```python
+import asyncio
+
+from webskrap import WebSkrapClient
+
+
+async def main() -> None:
+    async with WebSkrapClient() as client:
+        result = await client.fetch("https://example.com")
+        print(result.status)
+        print(result.title)
+
+
+asyncio.run(main())
+```
+
+## Features
+
+- Async Playwright lifecycle management.
+- One-shot fetch helper for simple scripts.
+- Persistent sessions with browser storage.
+- Built-in desktop and mobile profiles.
+- Custom profile support for locale, timezone, viewport, headers, and browser surfaces.
+- Resource routing presets.
+- CLI commands for fetches, profile inspection, and environment checks.
+
+## Next Steps
+
+- [Installation](getting-started/installation.md)
+- [Quickstart](getting-started/quickstart.md)
+- [Sessions](user-guide/sessions.md)
+- [API Reference](api-reference.md)

docs/index.md

@@ -0,0 +1,58 @@
+# WebSkrap
+
+WebSkrap is an async-first Python scraping framework built on Playwright.
+
+Repository: https://github.com/kacigaya/webskrap
+Documentation: https://kacigaya.github.io/webskrap/
+Package: https://pypi.org/project/webskrap/
+
+## Install
+
+```bash
+pip install webskrap
+python -m playwright install chromium
+```
+
+## Core API
+
+- `WebSkrapClient`: async context manager for Playwright lifecycle.
+- `WebSkrapSession`: persistent browser context wrapper.
+- `SessionConfig`: browser launch and context settings.
+- `BrowserProfile`: coherent browser-visible profile settings.
+- `StealthConfig`: configurable browser hardening toggles.
+- `FetchResult`: structured result returned from fetches.
+
+## Example
+
+```python
+import asyncio
+
+from webskrap import WebSkrapClient
+
+
+async def main() -> None:
+    async with WebSkrapClient() as client:
+        result = await client.fetch("https://example.com")
+        print(result.status)
+        print(result.title)
+
+
+asyncio.run(main())
+```
+
+## Boundaries
+
+WebSkrap does not include CAPTCHA solving, login-wall bypassing, credential bypassing, or access-control circumvention.
+
+## Important Links
+
+- Home: /
+- Installation: /getting-started/installation/
+- Quickstart: /getting-started/quickstart/
+- Client: /user-guide/client/
+- Sessions: /user-guide/sessions/
+- Profiles: /user-guide/profiles/
+- Stealth: /user-guide/stealth/
+- Resource Policy: /user-guide/resource-policy/
+- CLI: /user-guide/cli/
+- API Reference: /api-reference/