Add documentation workflow and mkdocs config (#48)

tr4nt0r · web-flow · commit bed350a16688 · 2025-11-09T16:23:19.000+01:00
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
@@ -0,0 +1,48 @@
+name: Build documentation
+
+on:
+  push:
+    branches:
+      - main
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+# Default to bash
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v5
+      - name: Install Hatch
+        uses: pypa/hatch@install
+      - name: Build
+        run: hatch run docs:build
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: ./site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/.gitignore b/.gitignore
@@ -74,3 +74,5 @@ target/
 # Node
 node_modules
 
+# mkdocs site
+site/
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1 @@
+--8<-- "README.md"
diff --git a/docs/reference/account.md b/docs/reference/account.md
@@ -0,0 +1,3 @@
+# Account provider
+
+::: pythonxbox.api.provider.account
diff --git a/docs/reference/account_models.md b/docs/reference/account_models.md
@@ -0,0 +1,3 @@
+# Account models
+
+::: pythonxbox.api.provider.account.models
diff --git a/docs/reference/achievements.md b/docs/reference/achievements.md
@@ -0,0 +1,3 @@
+# Achievements provider
+
+::: pythonxbox.api.provider.achievements
diff --git a/docs/reference/achievements_models.md b/docs/reference/achievements_models.md
@@ -0,0 +1,3 @@
+# Achievements models
+
+::: pythonxbox.api.provider.achievements.models
diff --git a/docs/reference/catalog.md b/docs/reference/catalog.md
@@ -0,0 +1,3 @@
+# Catalog provider
+
+::: pythonxbox.api.provider.catalog
diff --git a/docs/reference/catalog_models.md b/docs/reference/catalog_models.md
@@ -0,0 +1,3 @@
+# Catalog models
+
+::: pythonxbox.api.provider.catalog.models
diff --git a/docs/reference/client.md b/docs/reference/client.md
@@ -0,0 +1,3 @@
+# Xbox Live Client
+
+::: pythonxbox.api.client
diff --git a/docs/reference/cqs.md b/docs/reference/cqs.md
@@ -0,0 +1,3 @@
+# CSQ provider
+
+::: pythonxbox.api.provider.cqs
diff --git a/docs/reference/cqs_models.md b/docs/reference/cqs_models.md
@@ -0,0 +1,3 @@
+# CSQ models
+
+::: pythonxbox.api.provider.cqs.models
diff --git a/docs/reference/gameclips.md b/docs/reference/gameclips.md
@@ -0,0 +1,3 @@
+# Gameclips provider
+
+::: pythonxbox.api.provider.gameclips
diff --git a/docs/reference/gameclips_models.md b/docs/reference/gameclips_models.md
@@ -0,0 +1,3 @@
+# Gameclips models
+
+::: pythonxbox.api.provider.gameclips.models
diff --git a/docs/reference/language.md b/docs/reference/language.md
@@ -0,0 +1,3 @@
+# Language definitions
+
+::: pythonxbox.api.language
diff --git a/docs/reference/lists.md b/docs/reference/lists.md
@@ -0,0 +1,3 @@
+# Lists provider
+
+::: pythonxbox.api.provider.lists
diff --git a/docs/reference/lists_models.md b/docs/reference/lists_models.md
@@ -0,0 +1,3 @@
+# Lists models
+
+::: pythonxbox.api.provider.lists.models
diff --git a/docs/reference/manager.md b/docs/reference/manager.md
@@ -0,0 +1,3 @@
+# Authentication manager
+
+::: pythonxbox.authentication.manager
diff --git a/docs/reference/mediahub.md b/docs/reference/mediahub.md
@@ -0,0 +1,3 @@
+# Mediahub provider
+
+::: pythonxbox.api.provider.mediahub
diff --git a/docs/reference/mediahub_models.md b/docs/reference/mediahub_models.md
@@ -0,0 +1,3 @@
+# Mediahub models
+
+::: pythonxbox.api.provider.mediahub.models
diff --git a/docs/reference/message.md b/docs/reference/message.md
@@ -0,0 +1,3 @@
+# Message provider
+
+::: pythonxbox.api.provider.message
diff --git a/docs/reference/message_models.md b/docs/reference/message_models.md
@@ -0,0 +1,3 @@
+# Message models
+
+::: pythonxbox.api.provider.message.models
diff --git a/docs/reference/people.md b/docs/reference/people.md
@@ -0,0 +1,3 @@
+# People provider
+
+::: pythonxbox.api.provider.people
diff --git a/docs/reference/people_models.md b/docs/reference/people_models.md
@@ -0,0 +1,3 @@
+# People models
+
+::: pythonxbox.api.provider.people.models
diff --git a/docs/reference/presence.md b/docs/reference/presence.md
@@ -0,0 +1,3 @@
+# Presence provider
+
+::: pythonxbox.api.provider.presence
diff --git a/docs/reference/presence_models.md b/docs/reference/presence_models.md
@@ -0,0 +1,3 @@
+# Presence models
+
+::: pythonxbox.api.provider.presence.models
diff --git a/docs/reference/profile.md b/docs/reference/profile.md
@@ -0,0 +1,3 @@
+# Profile provider
+
+::: pythonxbox.api.provider.profile
diff --git a/docs/reference/profile_models.md b/docs/reference/profile_models.md
@@ -0,0 +1,3 @@
+# Profile models
+
+::: pythonxbox.api.provider.profile.models
diff --git a/docs/reference/pythonxbox.md b/docs/reference/pythonxbox.md
@@ -0,0 +1,35 @@
+# Reference
+
+::: pythonxbox.api.client
+::: pythonxbox.api.language
+::: pythonxbox.api.provider.account
+::: pythonxbox.api.provider.account.models
+::: pythonxbox.api.provider.cqs
+::: pythonxbox.api.provider.cqs.models
+::: pythonxbox.api.provider.gameclips
+::: pythonxbox.api.provider.gameclips.models
+::: pythonxbox.api.provider.lists
+::: pythonxbox.api.provider.lists.models
+::: pythonxbox.api.provider.mediahub
+::: pythonxbox.api.provider.mediahub.models
+::: pythonxbox.api.provider.message
+::: pythonxbox.api.provider.message.models
+::: pythonxbox.api.provider.people
+::: pythonxbox.api.provider.people.models
+::: pythonxbox.api.provider.presence
+::: pythonxbox.api.provider.presence.models
+::: pythonxbox.api.provider.profile
+::: pythonxbox.api.provider.profile.models
+::: pythonxbox.api.provider.screenshots
+::: pythonxbox.api.provider.screenshots.models
+::: pythonxbox.api.provider.smartglass
+::: pythonxbox.api.provider.smartglass.models
+::: pythonxbox.api.provider.titlehub
+::: pythonxbox.api.provider.titlehub.models
+::: pythonxbox.api.provider.usersearch
+::: pythonxbox.api.provider.usersearch.models
+::: pythonxbox.api.provider.userstats
+::: pythonxbox.api.provider.userstats.models
+::: pythonxbox.api.provider.ratelimitedprovider
+::: pythonxbox.authentication.manager
+::: pythonxbox.authentication.xal
diff --git a/docs/reference/screenshots.md b/docs/reference/screenshots.md
@@ -0,0 +1,3 @@
+# Screenshots provider
+
+::: pythonxbox.api.provider.screenshots
diff --git a/docs/reference/screenshots_models.md b/docs/reference/screenshots_models.md
@@ -0,0 +1,3 @@
+# Screenshots models
+
+::: pythonxbox.api.provider.screenshots.models
diff --git a/docs/reference/smartglass.md b/docs/reference/smartglass.md
@@ -0,0 +1,3 @@
+# Smartglass provider
+
+::: pythonxbox.api.provider.smartglass
diff --git a/docs/reference/smartglass_models.md b/docs/reference/smartglass_models.md
@@ -0,0 +1,3 @@
+# Smartglass models
+
+::: pythonxbox.api.provider.smartglass.models
diff --git a/docs/reference/titlehub.md b/docs/reference/titlehub.md
@@ -0,0 +1,3 @@
+# Titlehub provider
+
+::: pythonxbox.api.provider.titlehub
diff --git a/docs/reference/titlehub_models.md b/docs/reference/titlehub_models.md
@@ -0,0 +1,3 @@
+# Titlehub models
+
+::: pythonxbox.api.provider.titlehub.models
diff --git a/docs/reference/usersearch.md b/docs/reference/usersearch.md
@@ -0,0 +1,3 @@
+# Usersearch provider
+
+::: pythonxbox.api.provider.usersearch
diff --git a/docs/reference/usersearch_models.md b/docs/reference/usersearch_models.md
@@ -0,0 +1,3 @@
+# Usersearch models
+
+::: pythonxbox.api.provider.usersearch.models
diff --git a/docs/reference/userstats.md b/docs/reference/userstats.md
@@ -0,0 +1,3 @@
+# Userstats provider
+
+::: pythonxbox.api.provider.userstats
diff --git a/docs/reference/userstats_models.md b/docs/reference/userstats_models.md
@@ -0,0 +1,3 @@
+# Userstats models
+
+::: pythonxbox.api.provider.userstats.models
diff --git a/docs/reference/xalmanager.md b/docs/reference/xalmanager.md
@@ -0,0 +1,3 @@
+# XAL manager
+
+::: pythonxbox.authentication.xal
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -0,0 +1,109 @@
+site_name: python-xbox
+site_description: A library to authenticate with Xbox Network and use their API
+
+repo_url: https://github.com/tr4nt0r/python-xbox
+repo_name: tr4nt0r/python-xbox
+
+theme:
+    name: material
+    icon:
+        logo: material/library
+    palette:
+        # Palette toggle for automatic mode
+        - media: "(prefers-color-scheme)"
+          toggle:
+              icon: material/brightness-auto
+              name: Switch to light mode
+
+        # Palette toggle for light mode
+        - media: "(prefers-color-scheme: light)"
+          scheme: default
+          primary: pink
+          accent: purple
+          toggle:
+              icon: material/brightness-7
+              name: Switch to dark mode
+
+        # Palette toggle for dark mode
+        - media: "(prefers-color-scheme: dark)"
+          scheme: slate
+          primary: pink
+          accent: purple
+          toggle:
+              icon: material/brightness-4
+              name: Switch to light mode
+
+markdown_extensions:
+    - toc:
+          permalink: true
+    - pymdownx.highlight:
+          anchor_linenums: true
+    - pymdownx.tasklist:
+          custom_checkbox: true
+    - pymdownx.inlinehilite
+    - pymdownx.snippets
+    - pymdownx.superfences
+
+plugins:
+    - search
+    - mkdocstrings:
+          handlers:
+              python:
+                  paths: [src]
+                  inventories:
+                      - https://docs.python.org/3.14/objects.inv
+                  options:
+                      docstring_style: google
+                      merge_init_into_class: true
+                      show_root_members_full_path: true
+                      show_symbol_type_toc: true
+                      show_symbol_type_heading: true
+                      show_if_no_docstring: true
+                      members_order: source
+
+watch:
+    - docs
+    - src
+
+nav:
+    - About: index.md
+    - Reference:
+          - Xbox Live Client: reference/client.md
+          - Language definitions: reference/language.md
+          - Provider:
+                - Account: reference/account.md
+                - Achievements: reference/achievements.md
+                - Catalog: reference/catalog.md
+                - CQS: reference/cqs.md
+                - Gameclips: reference/gameclips.md
+                - Lists: reference/lists.md
+                - Mediahub: reference/mediahub.md
+                - Message: reference/message.md
+                - People: reference/people.md
+                - Presence: reference/presence.md
+                - Profile: reference/profile.md
+                - Screenshots: reference/screenshots.md
+                - Smartglass: reference/smartglass.md
+                - Titlehub: reference/titlehub.md
+                - Usersearch: reference/usersearch.md
+                - Userstats: reference/userstats.md
+          - Authentication:
+                - Authentication manager: reference/manager.md
+                - XAL manager: reference/xalmanager.md
+          - Models:
+                - Account: reference/account_models.md
+                - Achievements: reference/achievements_models.md
+                - Catalog: reference/catalog_models.md
+                - CQS: reference/cqs_models.md
+                - Gameclips: reference/gameclips_models.md
+                - Lists: reference/lists_models.md
+                - Mediahub: reference/mediahub_models.md
+                - Message: reference/message_models.md
+                - People: reference/people_models.md
+                - Presence: reference/presence_models.md
+                - Profile: reference/profile_models.md
+                - Screenshots: reference/screenshots_models.md
+                - Smartglass: reference/smartglass_models.md
+                - Titlehub: reference/titlehub_models.md
+                - Usersearch: reference/usersearch_models.md
+                - Userstats: reference/userstats_models.md
diff --git a/pyproject.toml b/pyproject.toml
@@ -119,6 +119,15 @@ dependencies = [
 ]
 config-path = "none"
 
+[tool.hatch.envs.docs]
+dependencies = [
+    "mkdocs-material==9.6.21",
+    "mkdocstrings[python]==0.30.1",
+]
+[tool.hatch.envs.docs.scripts]
+serve = "mkdocs serve"
+build = "mkdocs build"
+
 [build-system]
 requires = ["hatchling", "hatch-regex-commit"]
 build-backend = "hatchling.build"
