add documentation

Author: xoolive

.github/workflows/docs.yml

@@ -0,0 +1,46 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+      - master
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch: # Allow manual triggers
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Fetch all history for git info
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: |
+          uv pip install --system mkdocs-material
+
+      - name: Configure Git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Deploy to GitHub Pages
+        run: mkdocs gh-deploy --force

.gitignore

@@ -97,3 +97,4 @@ Thumbs.db
 systemd/
 _ignore/
 Icon
+site/

agents.md

@@ -7,7 +7,8 @@
 ## Coding style
 
 - Run `uv run ruff check` and `uv run ruff format` to check and format code
-- Run `uvx ty check src/ tests/` to check types
+- Run `uvx ty check kiosque/ tests/` to check types
+- Use `prettier` to format markdown files
 
 ## Commit rules
 

ARCHITECTURE.md docs/development/architecture.mdARCHITECTURE.md renamed to docs/development/architecture.md

@@ -69,7 +69,6 @@ Abstract base class for all website scrapers:
 **Key Components:**
 
 1. **Class Attributes:**
-
    - `base_url`: Website home URL (required)
    - `login_url`: Authentication endpoint (optional)
    - `alias`: List of short names for CLI (optional)
@@ -78,7 +77,6 @@ Abstract base class for all website scrapers:
    - `header_entries`: Custom HTTP headers (optional)
 
 2. **Core Methods:**
-
    - `instance(url)` - Factory method, returns appropriate Website subclass
    - `bs4(url)` - Fetch URL and return BeautifulSoup object
    - `login()` - Authenticate with website
@@ -186,7 +184,6 @@ Interactive bookmark browser built with [Textual](https://textual.textualize.io/
 **Components:**
 
 1. **`RaindropTUI` (Main App):**
-
    - Displays bookmarks from Raindrop.io
    - Auto-refresh every 5 minutes
    - Keyboard-driven interface
@@ -365,13 +362,11 @@ def get_with_retry(url, **kwargs):
 See `tests/` directory for implementation:
 
 1. **Unit Tests:**
-
    - Configuration validation (`test_config.py`)
    - Website base class (`test_website.py`)
    - API models (`test_raindrop.py`)
 
 2. **Integration Tests:**
-
    - Real login flows (`test_login.py`)
    - HTTP request/response handling
    - End-to-end article extraction (manual testing)
@@ -414,8 +409,8 @@ See `plan.md` for detailed future work, including:
 
 ## Related Documentation
 
-- [README.md](readme.md) - Quick start and usage
-- [CONTRIBUTING.md](CONTRIBUTING.md) - How to add new websites
-- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Common issues
-- [websites.md](websites.md) - Supported websites list
-- [plan.md](plan.md) - Future development roadmap
+- [Quick Start Guide](../index.md) - Getting started with Kiosque
+- [Contributing Guide](contributing.md) - How to add new websites
+- [Troubleshooting](../troubleshooting.md) - Common issues and solutions
+- [Supported Websites](../websites/supported-sites.md) - Complete list of supported sites
+- [Development Roadmap](roadmap.md) - Future development plans

CONTRIBUTING.md docs/development/contributing.mdCONTRIBUTING.md renamed to docs/development/contributing.md

@@ -50,12 +50,14 @@ uv run ruff check .
 ### Test Configuration
 
 **Login Tests:** Tests in `tests/test_login.py` require real credentials and are marked with `@pytest.mark.login`. These tests:
+
 - Make real HTTP requests to websites
 - Require credentials configured in `~/.config/kiosque/kiosque.conf`
 - Are automatically excluded in CI/CD to protect credentials
 - Should be run locally before submitting login-related changes
 
 **Running Tests:**
+
 ```bash
 # CI-safe tests only (no credentials required)
 uv run pytest -m "not login"
@@ -74,14 +76,12 @@ uv run pytest tests/test_login.py::test_website_login -k "lemonde"
 Before writing code, inspect the target website:
 
 1. **Find the article container:**
-
    - Open an article in your browser
    - Right-click the main article text → "Inspect Element"
    - Identify the HTML element containing the article (usually `<article>`, `<div class="article">`, etc.)
    - Note the CSS class or ID
 
 2. **Identify elements to remove:**
-
    - Look for elements to exclude: ads, "Read more" buttons, related articles, social media buttons
    - Note their HTML tags and classes
 
@@ -458,7 +458,7 @@ def article(self, url):
    ```
 
 3. **Update documentation:**
-   - Add website to `websites.md` in the appropriate language section
+   - Add website to [Supported Sites](../websites/supported-sites.md) in the appropriate language section
    - Indicate if authentication is supported (☑️)
 
 ### PR Guidelines
@@ -476,7 +476,6 @@ def article(self, url):
    ```
 
 3. **PR description should include:**
-
    - Brief description of the website
    - Whether authentication is supported
    - Any special considerations (e.g., "Login requires solving captcha manually")
@@ -511,7 +510,7 @@ Tested with the following articles:
 - [x] Code formatted with `ruff format`
 - [x] No linting errors (`ruff check`)
 - [x] Tests pass (`pytest`)
-- [x] Added website to `websites.md`
+- [x] Added website to [Supported Sites](../websites/supported-sites.md)
 - [x] Tested article extraction manually
 ```
 
@@ -598,7 +597,7 @@ def article(self, url):
 
 - **Issues:** Open a GitHub issue with the `website-support` label
 - **Questions:** Start a discussion in GitHub Discussions
-- **Documentation:** See [ARCHITECTURE.md](ARCHITECTURE.md) for system design
+- **Documentation:** See [Architecture](architecture.md) for system design
 - **Examples:** Check `kiosque/website/` for 30+ real implementations
 
 ## Thank You!