Add docs infrastructure and uv fixes

.github/workflows/deploy_mkdocs.yml

@@ -0,0 +1,20 @@
+name: Deploy MkDocs
+
+on:
+  push:
+    tags:
+      - "*"
+    branches:
+      - "enhancement/add-docs-infrastructure"
+  workflow_dispatch:
+
+jobs:
+  build-mk-docs:
+    # FIXME: Update @develop to @main after `ops-repo-automation` release.
+    uses: ynput/ops-repo-automation/.github/workflows/deploy_mkdocs.yml@develop
+    with:
+      repo: ${{ github.repository }}
+    secrets:
+      YNPUT_BOT_TOKEN: ${{ secrets.YNPUT_BOT_TOKEN }}
+      CI_USER: ${{ secrets.CI_USER }}
+      CI_EMAIL: ${{ secrets.CI_EMAIL }}

.github/workflows/pr_linting.yml

@@ -21,7 +21,13 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+      - name: Get changed files
+        id: changed-files
+        uses: tj-actions/changed-files@v46
+        with:
+          files: |
+            **.py
       - uses: astral-sh/ruff-action@v3
         with:
-          changed-files: "true"
           version-file: "pyproject.toml"
+          src: ${{ steps.changed-files.outputs.all_changed_files }}

docs/css/custom.css

@@ -0,0 +1,12 @@
+[data-md-color-scheme="slate"] {
+    /* simple slate overrides */
+    --md-primary-fg-color: hsl(155, 49%, 50%);
+    --md-accent-fg-color: rgb(93, 200, 156);
+    --md-typeset-a-color: hsl(155, 49%, 45%) !important;
+}
+[data-md-color-scheme="default"] {
+    /* simple default overrides */
+    --md-primary-fg-color: hsl(155, 49%, 50%);
+    --md-accent-fg-color: rgb(93, 200, 156);
+    --md-typeset-a-color: hsl(155, 49%, 45%) !important;
+}

docs/index.md

@@ -0,0 +1 @@
+--8<-- "README.md"

docs/license.md

@@ -0,0 +1 @@
+--8<-- "LICENSE"

mkdocs.yml

@@ -0,0 +1,71 @@
+site_name: ayon-addon-template
+repo_url: https://github.com/ynput/ayon-addon-template
+
+nav:
+  - Home: index.md
+  - License: license.md
+
+theme:
+  name: material
+  palette:
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      toggle:
+        icon: material/weather-night
+        name: Switch to dark mode
+  logo: img/ay-symbol-blackw-full.png
+  favicon: img/favicon.ico
+  features:
+    - navigation.sections
+    - navigation.path
+    - navigation.prune
+
+extra:
+  version:
+    provider: mike
+
+extra_css: [css/custom.css]
+
+markdown_extensions:
+  - mdx_gh_links
+  - pymdownx.snippets
+
+plugins:
+  - search
+  - offline
+  - mkdocs-autoapi:
+      autoapi_dir: ./
+      autoapi_add_nav_entry: Reference
+      autoapi_ignore:
+        - .*
+        - docs/**/*
+        - tests/**/*
+        - tools/**/*
+        - stubs/**/*        # mocha fix
+        - ./**/pythonrc.py  # houdini fix
+        - .*/**/*
+        - ./*.py
+  - mkdocstrings:
+      handlers:
+        python:
+          paths:
+            - ./
+            - client/*
+            - server/*
+            - services/*
+  - minify:
+      minify_html: true
+      minify_js: true
+      minify_css: true
+      htmlmin_opts:
+        remove_comments: true
+      cache_safe: true
+  - mike
+
+hooks:
+  - mkdocs_hooks.py

mkdocs_hooks.py

@@ -0,0 +1,191 @@
+import os
+from pathlib import Path
+from shutil import rmtree
+import json
+import glob
+import logging
+
+TMP_FILE = "./missing_init_files.json"
+NFILES = []
+
+# -----------------------------------------------------------------------------
+
+
+class ColorFormatter(logging.Formatter):
+    grey = "\x1b[38;20m"
+    green = "\x1b[32;20m"
+    yellow = "\x1b[33;20m"
+    red = "\x1b[31;20m"
+    bold_red = "\x1b[31;1m"
+    reset = "\x1b[0m"
+    fmt = (
+        "%(asctime)s - %(name)s - %(levelname)s - %(message)s "  # noqa
+        "(%(filename)s:%(lineno)d)"
+    )
+
+    FORMATS = {
+        logging.DEBUG: grey + fmt + reset,
+        logging.INFO: green + fmt + reset,
+        logging.WARNING: yellow + fmt + reset,
+        logging.ERROR: red + fmt + reset,
+        logging.CRITICAL: bold_red + fmt + reset,
+    }
+
+    def format(self, record):
+        log_fmt = self.FORMATS.get(record.levelno)
+        formatter = logging.Formatter(log_fmt)
+        return formatter.format(record)
+
+
+ch = logging.StreamHandler()
+ch.setFormatter(ColorFormatter())
+
+logging.basicConfig(
+    level=logging.INFO,
+    handlers=[ch],
+)
+
+
+# -----------------------------------------------------------------------------
+
+
+def create_init_file(dirpath, msg):
+    global NFILES
+    ini_file = f"{dirpath}/__init__.py"
+    Path(ini_file).touch()
+    NFILES.append(ini_file)
+    logging.info(f"{msg}: created '{ini_file}'")
+
+
+def create_parent_init_files(dirpath: str, rootpath: str, msg: str):
+    parent_path = dirpath
+    while parent_path != rootpath:
+        parent_path = os.path.dirname(parent_path)
+        parent_init = os.path.join(parent_path, "__init__.py")
+        if not os.path.exists(parent_init):
+            create_init_file(parent_path, msg)
+        else:
+            break
+
+
+def add_missing_init_files(*roots, msg=""):
+    """
+    This function takes in one or more root directories as arguments and scans
+    them for Python files without an `__init__.py` file. It generates a JSON
+    file named `missing_init_files.json` containing the paths of these files.
+
+    Args:
+        *roots: Variable number of root directories to scan.
+
+    Returns:
+        None
+    """
+
+    for root in roots:
+        if not os.path.exists(root):
+            continue
+        rootpath = os.path.abspath(root)
+        for dirpath, dirs, files in os.walk(rootpath):
+            if "__init__.py" in files:
+                continue
+
+            if "." in dirpath:
+                continue
+
+            if not glob.glob(os.path.join(dirpath, "*.py")):
+                continue
+
+            create_init_file(dirpath, msg)
+            create_parent_init_files(dirpath, rootpath, msg)
+
+    with open(TMP_FILE, "w") as f:
+        json.dump(NFILES, f)
+
+
+def remove_missing_init_files(msg=""):
+    """
+    This function removes temporary `__init__.py` files created in the
+    `add_missing_init_files()` function. It reads the paths of these files from
+    a JSON file named `missing_init_files.json`.
+
+    Args:
+        None
+
+    Returns:
+        None
+    """
+    global NFILES
+    nfiles = []
+    if os.path.exists(TMP_FILE):
+        with open(TMP_FILE, "r") as f:
+            nfiles = json.load(f)
+    else:
+        nfiles = NFILES
+
+    for file in nfiles:
+        Path(file).unlink()
+        logging.info(f"{msg}: removed {file}")
+
+    os.remove(TMP_FILE)
+    NFILES = []
+
+
+def remove_pychache_dirs(msg=""):
+    """
+    This function walks the current directory and removes all existing
+    '__pycache__' directories.
+
+    Args:
+        msg: An optional message to display during the removal process.
+
+    Returns:
+        None
+    """
+    nremoved = 0
+
+    for dirpath, dirs, files in os.walk("."):
+        if "__pycache__" in dirs:
+            pydir = Path(f"{dirpath}/__pycache__")
+            rmtree(pydir)
+            nremoved += 1
+            logging.info(f"{msg}: removed '{pydir}'")
+
+    if not nremoved:
+        logging.info(f"{msg}: no __pycache__ dirs found")
+
+
+# mkdocs hooks ----------------------------------------------------------------
+
+
+def on_startup(command, dirty):
+    remove_pychache_dirs(msg="HOOK    -  on_startup")
+
+
+def on_pre_build(config):
+    """
+    This function is called before the MkDocs build process begins. It adds
+    temporary `__init__.py` files to directories that do not contain one, to
+    make sure mkdocs doesn't ignore them.
+    """
+    try:
+        add_missing_init_files(
+            "client",
+            "server",
+            "services",
+            msg="HOOK    -  on_pre_build",
+        )
+    except BaseException as e:
+        logging.error(e)
+        remove_missing_init_files(
+            msg="HOOK    -  on_post_build: cleaning up on error !"
+        )
+        raise
+
+
+def on_post_build(config):
+    """
+    This function is called after the MkDocs build process ends. It removes
+    temporary `__init__.py` files that were added in the `on_pre_build()`
+    function.
+    """
+    remove_missing_init_files(msg="HOOK    -  on_post_build")

mkdocs_requirements.txt

@@ -0,0 +1,9 @@
+mkdocs-material >= 9.6.7
+mkdocs-autoapi >= 0.4.0
+mkdocstrings-python >= 1.16.2
+mkdocs-minify-plugin >= 0.8.0
+markdown-checklist >= 0.4.4
+mdx-gh-links >= 0.4
+pymdown-extensions >= 10.14.3
+mike >= 2.1.3
+mkdocstrings-shell >= 1.0.2

pre-commit-config.yaml

@@ -0,0 +1,27 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+    - repo: https://github.com/pre-commit/pre-commit-hooks
+      rev: v4.4.0
+      hooks:
+            - id: trailing-whitespace
+            - id: end-of-file-fixer
+            - id: check-yaml
+            - id: check-added-large-files
+            - id: no-commit-to-branch
+              args: [ '--pattern', '^(?!((release|enhancement|feature|bugfix|documentation|tests|local|chore)\/[a-zA-Z0-9\-_]+)$).*' ]
+    - repo: https://github.com/codespell-project/codespell
+      rev: v2.2.6
+      hooks:
+      - id: codespell
+        additional_dependencies:
+          - tomli
+
+    - repo: https://github.com/astral-sh/ruff-pre-commit
+      # Ruff version.
+      rev: v0.15.0
+      hooks:
+        # Run the linter.
+        - id: ruff
+        # Run the formatter.
+        # - id: ruff-format

pyproject.toml

@@ -4,23 +4,21 @@
 # be used only for local development and CI/CD purposes. To define addon
 # dependencies, use pyproject.toml file in the `client` directory.
 
-
 [project]
 name = "ayon-addon-template"
 version = "0.1.0"
 description = "Add your description here"
 license = "Apache-2.0"
 readme = "README.md"
 requires-python = ">=3.9.6"
-dependencies = []
+dependencies = [
+    "pre-commit",
+    "ruff ~= 0.15.0",
+    "mypy"
+]
 
 [project.optional-dependencies]
 dev = [
     "pytest",
     "codespell",
-    "ruff ~= 0.11.4",
-    "flake8",
-    "mypy", 
-    "isort", 
-    "pre-commit"
 ]