docs: скриншоты UI (светлая/тёмная тема) в app/docs и README

- app/docs/screenshots.md и каталог app/docs/images/*.png - раздача /static/docs-images/* из FastAPI; documentation.js переписывает src картинок - стили .markdown-body img; строка в api_routes.md; превью в README
2026-04-05 01:18:22 +03:00
parent ec5eedb838
commit c49555b3b9
16 changed files with 120 additions and 2 deletions
@@ -1,7 +1,5 @@
 # Kind Clusters Dashboard — локальные кластеры Kubernetes (kind)
 **Репозиторий Git:** `ssh://git@git.antropoff.ru:222/DevOpsTools/KindClustersDashboard.git` — клон: `git clone ssh://git@git.antropoff.ru:222/DevOpsTools/KindClustersDashboard.git`. Уже клонировали раньше: `git remote set-url origin ssh://git@git.antropoff.ru:222/DevOpsTools/KindClustersDashboard.git`.
 Образ **kind-k8s-tools:local** и **Makefile** поднимают **веб-интерфейс** (FastAPI) на порту **8080** на хосте по умолчанию (или **`KIND_K8S_WEB_PORT`** в `.env`; внутри контейнера приложение слушает **6000**). Порт **6000 на хосте** не используем по умолчанию: Chrome и другие браузеры на Chromium отдают **ERR_UNSAFE_PORT**. Через браузер создаёте и удаляете кластеры, смотрите статистику и вывод `kubectl`. **kubeconfig** сохраняется в `clusters/<имя>/`. На хосте достаточно **Docker** (или Podman) и **make**; **kind** и **kubectl** — внутри контейнера.
 ## Документация
@@ -9,8 +7,17 @@
 | Ресурс | Описание |
 |--------|----------|
 | **[app/docs/api_routes.md](app/docs/api_routes.md)** | Описание REST API `/api/v1/*` с примерами JSON (для фронтенда и интеграций) |
 | **[app/docs/screenshots.md](app/docs/screenshots.md)** | Скриншоты веб-интерфейса (**светлая** и **тёмная** тема); файлы в **`app/docs/images/`** |
 | **`/docs`** (Swagger), **`/redoc`**, **`/api/v1/health`** | На панели открываются в **отдельном окне** браузера (`window.open`); прямой URL — тот же порт, что и UI (по умолчанию **8080**) |
 ### Скриншоты (превью)
 Полная галерея и подписи — в **[app/docs/screenshots.md](app/docs/screenshots.md)**. Ниже — главная панель в обеих темах.
 | Светлая тема | Тёмная тема |
 | :------------: | :-----------: |
 | ![](app/docs/images/dashboard-light.png) | ![](app/docs/images/dashboard-dark.png) |
 В корне репозитория — файл **`env.example`**: перечислены **только имена** переменных (без значений), для ориентира при ручной настройке **`.env`**. Полноценно создать **`.env`** можно интерактивно скриптом **`scripts/setup_env_interactive.py`** (`make setup`; в начале — выбор **docker** или **podman**, путь **`CONTAINER_SOCKET`** подставляется автоматически).
 ## Зачем это нужно
@@ -28,6 +28,7 @@
 | `GET /documentation` | HTML-оболочка; **`documentation.js`**: без `path` — **`GET /api/v1/docs/readme`**, с `?path=app/docs/…` — **`GET /api/v1/docs/file`**; разбор Markdown из **`/static/js/vendor/`** (marked, DOMPurify). Полноэкранный спиннер при первой загрузке и при **каждом** переходе по внутренним ссылкам / **popstate**. Каждая секция по **H2** — **одна карточка** (заголовок h2 и содержимое до следующего h2 вместе). Заголовок вкладки браузера: **«Документация — …»** + текст **первого H1** документа + имя приложения (`KIND_K8S_APP_TITLE` на `body`). В шапке на этой странице активна только **Документация**; **Панель** как обычная пилюля (на дашборде активна **Панель**). Путь к README: `KIND_K8S_README_PATH` или `README.md` рядом с `app/`; в образе — `/opt/kind-k8s/README.md`. |
 | `GET /ui` | Редирект **307** на `/` (удобный ярлык). |
 | `GET /static/…` | CSS (`style.css`), скрипты панели (`js/dashboard.js`) и документации (`js/documentation.js`); базовый URL API задаётся атрибутом `data-api-base` на `<body>` (по умолчанию `/api/v1`). |
 | `GET /static/docs-images/…` | PNG из **`app/docs/images/`** для страницы **`/documentation`** (в Markdown пути вида `images/*.png` в **`documentation.js`** переписываются на этот префикс; см. **`app/docs/screenshots.md`**). |
 Шаблоны: `app/templates/base.html` (шапка, навигация; **меню «гамбургер»** при узком viewport — `nav-mobile.js`), `app/templates/dashboard.html` (панель), `app/templates/clusters.html` (список кластеров и донаты узлов), `app/templates/cluster_create.html` (создание кластера и последние задания), `app/templates/cluster_detail.html` (страница кластера), `app/templates/cluster_edit.html` (редактирование конфигурации), `app/templates/cluster_addons.html` (Helm-аддоны), `app/templates/journal.html` (журнал заданий), `app/templates/documentation.html` (README и `app/docs/*.md`).
@@ -0,0 +1,63 @@
 # Скриншоты интерфейса
 Снимки экрана в **светлой** и **тёмной** теме (переключатель темы в шапке). Исходные файлы лежат в каталоге **`app/docs/images/`** (в репозитории рядом с этим файлом).
 Открыть в веб-приложении: страница **«Документация»** → путь **`app/docs/screenshots.md`**.
 ---
 ## Главная панель
 **Светлая тема**
 ![Главная панель, светлая тема](images/dashboard-light.png)
 **Тёмная тема**
 ![Главная панель, тёмная тема](images/dashboard-dark.png)
 ## Страница «Кластеры»
 Снимок в тёмной теме (отдельный скрин светлой темы не добавлялся).
 ![Кластеры, тёмная тема](images/clusters-dark.png)
 ## Создание кластера
 Снимок в светлой теме.
 ![Создание кластера, светлая тема](images/create-cluster-light.png)
 ## Аддоны (Helm)
 **Светлая тема**
 ![Аддоны, светлая тема](images/addons-light.png)
 **Тёмная тема**
 ![Аддоны, тёмная тема](images/addons-dark.png)
 ## Встроенная документация (Markdown)
 **Светлая тема**
 ![Документация в UI, светлая тема](images/docs-light.png)
 **Тёмная тема**
 ![Документация в UI, тёмная тема](images/docs-dark.png)
 ## Журнал
 **Светлая тема**
 ![Журнал, светлая тема](images/logs-light.png)
 **Тёмная тема**
 ![Журнал, тёмная тема](images/logs-dark.png)
 ---
 *Автор: Сергей Антропов — https://devops.org.ru*
@@ -57,6 +57,15 @@ _static_dir = _BASE / "static"
 if _static_dir.is_dir():
    app.mount("/static", StaticFiles(directory=str(_static_dir)), name="static")
 # PNG-скриншоты для app/docs/screenshots.md и др.: относительные пути images/* в Markdown → /static/docs-images/*
 _docs_images_dir = _BASE / "docs" / "images"
 if _docs_images_dir.is_dir():
    app.mount(
        "/static/docs-images",
        StaticFiles(directory=str(_docs_images_dir)),
        name="docs_images",
    )
 templates = Jinja2Templates(directory=str(_templates_dir))
@@ -139,6 +139,33 @@
    });
  }
  /**
   * Картинки из app/docs/*.md с src вида images/foo.png → /static/docs-images/foo.png
   * (каталог app/docs/images смонтирован в FastAPI как StaticFiles).
   */
  function rewriteMdImages(container, currentDocPath) {
    if (!currentDocPath || currentDocPath.indexOf("app/docs/") !== 0) return;
    var baseDir = currentDocPath.replace(/[^/]+\.md$/i, "");
    if (!baseDir) return;
    container.querySelectorAll("img[src]").forEach(function (img) {
      var src = (img.getAttribute("src") || "").trim();
      if (!src || /^https?:\/\//i.test(src) || src.startsWith("data:")) return;
      if (src.indexOf("..") >= 0) return;
      if (src.startsWith("/static/docs-images/")) return;
      try {
        var u = new URL(src, "http://doc.local/" + baseDir);
        var pathname = decodeURIComponent(u.pathname.replace(/^\/+/, ""));
        if (pathname.indexOf("..") >= 0) return;
        if (!pathname.startsWith("app/docs/images/")) return;
        var rest = pathname.replace(/^app\/docs\/images\/?/, "");
        if (!rest) return;
        img.setAttribute("src", "/static/docs-images/" + rest);
      } catch (e) {
        /* ignore */
      }
    });
  }
  /** Текст первого H1 в разобранном HTML (для заголовка вкладки). */
  function extractFirstH1Text(root) {
    var h = root.querySelector("h1");
@@ -261,6 +288,7 @@
      var temp = document.createElement("div");
      temp.innerHTML = DOMPurify.sanitize(rawHtml);
      rewriteMdLinks(temp, docPath);
      rewriteMdImages(temp, docPath);
      var h1ForTitle = extractFirstH1Text(temp);
      applyDocumentationTabTitle(h1ForTitle);
@@ -2935,6 +2935,16 @@ button.btn-danger:hover {
 .readme-section-card.markdown-body li {
  margin: 0.2rem 0;
 }
 /* Скриншоты в app/docs/screenshots.md: не вылезают за карточку */
 .readme-section-card.markdown-body img {
  max-width: 100%;
  height: auto;
  border-radius: 8px;
  margin: 0.5rem 0;
  border: 1px solid var(--color-border-subtle, rgba(128, 128, 128, 0.25));
 }
 .readme-section-card.markdown-body a {
  color: var(--accent);
  text-decoration: underline;