Add readthedocs

.github/workflows/publish.yaml

@@ -8,8 +8,6 @@ on:
 jobs:
   publish-to-pypi:
     name: Publish Python distribution to PyPI
-    needs:
-      - build
     runs-on: ubuntu-latest
     environment:
       name: pypi

.gitignore

@@ -3,3 +3,4 @@ __pycache__
 venv
 dist
 .vscode/PythonImportHelper-v2-Completion.json
+site/

.readthedocs.yaml

@@ -0,0 +1,16 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+  jobs:
+    post_create_environment:
+      - pip install poetry
+    post_install:
+      # VIRTUAL_ENV needs to be set manually for now.
+      # See https://github.com/readthedocs/readthedocs.org/pull/11152/
+      - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH poetry install --extras docs
+
+mkdocs:
+  configuration: mkdocs.yaml

docs/README.md

@@ -0,0 +1 @@
+../README.md

mkdocs.yaml

@@ -0,0 +1,30 @@
+site_name: MySkoda
+theme:
+  name: readthedocs
+  highlightjs: true
+
+watch:
+  - README.md
+
+plugins:
+  - autorefs
+  - search
+  - gen-files:
+      scripts:
+      - scripts/gen_ref_nav.py
+  - literate-nav:
+      nav_file: SUMMARY.md
+  - mkdocstrings:
+      default_handler: python
+      handlers:
+        python:
+          paths: [myskoda]
+
+nav:
+  - Home:
+    - Overview: README.md
+  - API reference:
+    - myskoda: reference/
+  - Reverse Engineering:
+    - MQTT: mqtt.md
+    - Rest API: rest.md

pyproject.toml

@@ -16,7 +16,11 @@ pyjwt = "^2"
 python = ">=3.12.0"
 pyyaml = "^6"
 termcolor = { version = "^2.4.0", optional = true }
-mashumaro = {extras = ["orjson"], version = "^3.13.1"}
+mashumaro = { extras = ["orjson"], version = "^3.13.1" }
+mkdocs = { extras = ["gen-files"], version = "^1.6.1", optional = true }
+mkdocstrings = { extras = ["python"], version = "^0.26.1", optional = true }
+mkdocs-gen-files = { version = "^0.5.0", optional = true }
+mkdocs-literate-nav = { version = "^0.6.1", optional = true }
 
 [tool.poetry.group.dev.dependencies]
 pyright = "^1.1.379"
@@ -29,6 +33,7 @@ myskoda = "myskoda.cli:cli"
 
 [tool.poetry.extras]
 cli = ["asyncclick", "coloredlogs", "termcolor"]
+docs = ["mkdocs", "mkdocstrings", "mkdocs-gen-files", "mkdocs-literate-nav"]
 
 [build-system]
 build-backend = "poetry.core.masonry.api"
@@ -41,17 +46,18 @@ target-version = "py312"
 [tool.ruff.lint]
 ignore = [
     "COM812", # missing-trailing-comma
-    "D101",   # undocumented-public-class
-    "D103",   # undocumented-public-function
-    "D203",   # one-blank-line-before-class
-    "D211",   # blank-line-before-class
-    "D213",   # multi-line-summary-second-line
+    "D101", # undocumented-public-class
+    "D103", # undocumented-public-function
+    "D203", # one-blank-line-before-class
+    "D211", # blank-line-before-class
+    "D213", # multi-line-summary-second-line
     "FBT001", # boolean-type-hint-positional-argument
     "FIX002", # line-contains-todo
-    "G004",   # logging-f-string
+    "G004", # logging-f-string
     "ISC001", # single-line-implicit-string-concatenation
-    "S101",   # assert (used in tests)
-    "T201",   # print
-    "TD003",  # missing-todo-link
+    "S101", # assert (used in tests)
+    "T201", # print
+    "TD003", # missing-todo-link
+
 ]
 select = ["ALL"]

scripts/gen_ref_nav.py

@@ -0,0 +1,42 @@
+"""Generate the code reference pages and navigation."""
+
+from pathlib import Path
+
+import mkdocs_gen_files
+
+nav = mkdocs_gen_files.Nav()
+mod_symbol = '<code class="doc-symbol doc-symbol-nav doc-symbol-module"></code>'
+
+root = Path(__file__).parent.parent
+src = root / "myskoda"
+
+for path in sorted(src.rglob("*.py")):
+    module_path = path.relative_to(src).with_suffix("")
+    doc_path = path.relative_to(src).with_suffix(".md")
+    full_doc_path = Path("reference", doc_path)
+
+    parts = tuple(module_path.parts)
+
+    if parts[-1] == "__init__":
+        parts = parts[:-1]
+        doc_path = doc_path.with_name("index.md")
+        full_doc_path = full_doc_path.with_name("index.md")
+        print(parts, doc_path, full_doc_path)
+    elif parts[-1].startswith("_"):
+        continue
+
+    if len(parts) == 0:
+        continue
+
+    nav_parts = [f"{mod_symbol} {part}" for part in parts]
+    print(nav_parts, doc_path.as_posix())
+    nav[tuple(nav_parts)] = doc_path.as_posix()
+
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        ident = ".".join(parts)
+        fd.write(f"---\ntitle: {ident}\n---\n\n::: {ident}")
+
+    mkdocs_gen_files.set_edit_path(full_doc_path, ".." / path.relative_to(root))
+
+with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
+    nav_file.writelines(nav.build_literate_nav())