docs: migrate documentation from Sphinx/Read the Docs to VitePress with GitHub Pages deployment

.github/workflows/deploy-docs.yaml

@@ -0,0 +1,62 @@
+---
+name: Deploy docs to GitHub Pages
+
+# yamllint disable-line rule:truthy
+on:
+  push:
+    branches: [main, feature/migrate-from-read-the-docs]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - name: ⤵️ Check out code from GitHub
+        uses: actions/checkout@v4.1.1
+        with:
+          fetch-depth: 0
+      - name: 🏗 Set up Python
+        uses: actions/setup-python@v5.0.0
+        with:
+          python-version: "3.12"
+      - name: 🏗 Install uv
+        uses: astral-sh/setup-uv@v7
+      - name: 🏗 Install project dependencies
+        run: uv sync
+      - name: 🏗 Install pydoc-markdown
+        run: uv pip install pydoc-markdown --system
+      - name: 🏗 Set up Node.js
+        uses: actions/setup-node@v4.0.2
+        with:
+          node-version-file: ".nvmrc"
+          cache: "npm"
+      - name: 🏗 Install dependencies
+        run: npm ci
+      - name: 🔨 Build with VitePress
+        run: npm run docs:build
+      - name: 📦 Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/.vitepress/dist
+
+  deploy:
+    name: Deploy
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: 🚀 Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -77,8 +77,14 @@ coverage.xml
 # Django stuff:
 *.log
 
-# Sphinx documentation
-docs/_build/
+# VitePress
+docs/.vitepress/cache
+docs/.vitepress/dist
+
+# Auto-generated docs (created by scripts/generate_docs.py via pydoc-markdown)
+docs/api.md
+docs/models.md
+docs/exceptions.md
 
 # pyenv
 .python-version

.prettierignore

@@ -77,8 +77,14 @@ coverage.xml
 # Django stuff:
 *.log
 
-# Sphinx documentation
-docs/_build/
+# VitePress
+docs/.vitepress/cache
+docs/.vitepress/dist
+
+# Auto-generated docs
+docs/api.md
+docs/models.md
+docs/exceptions.md
 
 # pyenv
 .python-version

README.md

@@ -8,8 +8,8 @@
 
 [![Build Status][build-shield]][build]
 [![Code Coverage][codecov-shield]][codecov]
+[![Documentation][docs-shield]][docs]
 [![Quality Gate Status][sonarcloud-shield]][sonarcloud]
-[![Documentation Status][readthedocs-shield]][readthedocs]
 [![Open in Dev Containers][devcontainer-shield]][devcontainer]
 
 Asynchronous Python client to control Tado devices.
@@ -22,7 +22,8 @@ Not all endpoints and features are fully supported.
 This is the continuation project of PyTado.
 
 ## Documentation
-A full documentation can be found at [Read the Docs][readthedocs].
+
+Full documentation is available at [GitHub Pages][docs].
 
 ## Installation
 
@@ -168,6 +169,8 @@ SOFTWARE.
 [contributors]: https://github.com/erwindouna/python-tado/graphs/contributors
 [devcontainer-shield]: https://img.shields.io/static/v1?label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode
 [devcontainer]: https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/erwindouna/python-tado
+[docs]: https://erwindouna.github.io/python-tado/
+[docs-shield]: https://github.com/erwindouna/python-tado/actions/workflows/deploy-docs.yaml/badge.svg
 [erwindouna]: https://github.com/erwindouna
 [github-sponsors-shield]: https://erwindouna.dev/wp-content/uploads/2019/12/github_sponsor.png
 [github-sponsors]: https://github.com/sponsors/erwindouna
@@ -185,5 +188,3 @@ SOFTWARE.
 [semver]: http://semver.org/spec/v2.0.0.html
 [sonarcloud-shield]: https://sonarcloud.io/api/project_badges/measure?project=erwindouna_python-tado&metric=alert_status
 [sonarcloud]: https://sonarcloud.io/summary/new_code?id=erwindouna_python-tado
-[readthedocs-shield]: https://readthedocs.org/projects/python-tado/badge/?version=latest
-[readthedocs]: https://python-tado.readthedocs.io/en/latest/index.html

docs/.vitepress/config.mts

@@ -0,0 +1,43 @@
+import { defineConfig } from "vitepress";
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  base: "/python-tado/",
+  title: "Tado Async",
+  description:
+    "Asynchronous Python client for controlling Tado devices, mainly used for Home Assistant",
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-config
+    nav: [
+      { text: "Home", link: "/" },
+      { text: "Usage", link: "/usage" },
+      { text: "API", link: "/api" },
+      { text: "Models", link: "/models" },
+      { text: "Exceptions", link: "/exceptions" },
+    ],
+
+    sidebar: [
+      {
+        text: "Documentation",
+        items: [
+          { text: "Home", link: "/" },
+          { text: "Usage", link: "/usage" },
+          { text: "API Reference", link: "/api" },
+          { text: "Models Reference", link: "/models" },
+          { text: "Exceptions Reference", link: "/exceptions" },
+        ],
+      },
+    ],
+
+    search: {
+      provider: "local",
+    },
+
+    socialLinks: [
+      {
+        icon: "github",
+        link: "https://github.com/erwindouna/python-tado",
+      },
+    ],
+  },
+});

docs/index.md

@@ -0,0 +1,35 @@
+---
+# https://vitepress.dev/reference/default-theme-home-page
+layout: home
+
+hero:
+  name: "Tado Async"
+  text: "Asynchronous Python client for the Tado API"
+  tagline: Control Tado devices from within Python, mainly used for Home Assistant.
+  actions:
+    - theme: brand
+      text: Get Started
+      link: /usage
+    - theme: alt
+      text: API Reference
+      link: /api
+
+features:
+  - title: Async Support
+    details: Fully asynchronous Python client using aiohttp for non-blocking I/O.
+  - title: Home Assistant
+    details: Designed for use within Home Assistant, but can also be used standalone.
+  - title: Comprehensive API
+    details: Covers zones, devices, weather, capabilities, overlays, and more.
+---
+
+## About
+
+**Tado Async** is a Python library that allows you to control Tado devices.
+Although it can be used as a standalone package, its current scope is to be used within Home Assistant.
+Not all endpoints and features are fully supported.
+This is the continuation project of PyTado.
+
+::: warning
+This project is under active development.
+:::