New Docs and Tutorials

.github/workflows/test_suite.yml

@@ -96,23 +96,38 @@ jobs:
           token: ${{ secrets.CODECOV_TOKEN }}
 
   docs:
-    name: Docs Build
+    name: 📚 Docs Build & Examples Tests
     runs-on: ubuntu-latest
     timeout-minutes: 15
+    needs: setup-browsers
     steps:
       - name: Checkout
         uses: actions/checkout@v4
 
       - name: Setup Python
         uses: actions/setup-python@v5
         with:
-          python-version: "3.x"
+          python-version: "3.13"
           cache: 'pip'
 
+      - name: Install Playwright
+        run: pip install playwright
+
+      - name: Restore Playwright browsers cache
+        uses: actions/cache/restore@v4
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-${{ runner.os }}-${{ needs.setup-browsers.outputs.playwright-version }}-browsers
+          fail-on-cache-miss: true
+
       - name: Install Deps
         run: |
           pip install -U pip wheel
-          pip install .[docs]
+          pip install -e .[docs,test]
+
+      - name: Run Example Tests (Headless)
+        run: |
+          pytest docs/examples --headless -vv
 
       - name: Build Docs
         run: sphinx-build -b html -d build/sphinx-doctrees docs build/htmldocs

.pre-commit-config.yaml

@@ -16,3 +16,4 @@ repos:
     rev: v1.18.2
     hooks:
       - id: mypy
+        exclude: ^docs/examples/

.readthedocs.yaml

@@ -6,10 +6,20 @@ version: 2
 
 # Set the OS, Python version and other tools you might need
 build:
-  os: ubuntu-22.04
+  os: ubuntu-24.04
   tools:
-    python: "3.12"
+    python: "3.13"
+
+# Install Python dependencies
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs
 
 # Build documentation in the "docs/" directory with Sphinx
 sphinx:
   configuration: docs/conf.py
+  builder: html
+  fail_on_warning: false

docs/README.md

@@ -0,0 +1,47 @@
+# Widgetastic.Core Documentation
+
+This directory contains the comprehensive documentation for widgetastic.core, providing a superior learning experience for developers using this powerful web automation framework.
+
+## 🏗️ Building the Documentation
+
+### Prerequisites
+
+```bash
+# For the full documentation experience, install widgetastic.core with doc dependencies.
+pip install -e .[docs]
+```
+
+### Building HTML Documentation
+
+From the project root:
+
+```bash
+cd docs
+sphinx-build -b html . _build/html
+```
+
+The documentation will be built in `_build/html/`. Open `_build/html/index.html` in your browser to view.
+
+### Live Development Server
+
+For live reloading during development:
+
+```bash
+sphinx-autobuild . _build/html --watch ../src
+```
+
+This will start a development server at `http://localhost:8000` with automatic rebuilding when files change.
+
+### Building Other Formats
+
+```bash
+# PDF documentation
+sphinx-build -b latex . _build/latex
+cd _build/latex && make
+
+# EPUB format
+sphinx-build -b epub . _build/epub
+
+# Single HTML file
+sphinx-build -b singlehtml . _build/singlehtml
+```