upd

2026-06-05 11:37:27 +05:00
parent af66306db0
commit 92be7b9965
7 changed files with 238 additions and 104 deletions
@@ -1,62 +1,21 @@
-# MkDocs
-## Инструкция по установке есть на сайте MkDocs.

-### Надо установить:
+# Разработка документации (Zensical)

-python python.org
-pip – менеджер пакет (ставится, обычно, вместе с питоном)
-mkdocs – пакет с движком mkdocs
+## Локальная разработка с live-превью

-`pip install mkdocs`
-Полезные ссылки:
+**Zensical** имеет встроенный dev-сервер с **live-reload** — это полноценная и более быстрая замена старой команде `mkdocs serve`.

-mkdocs.org
+### Как запустить

-### плагины MkDocs
+1. Установите Zensical:

-Темы MkDocs
+```bash
+pip install zensical

-markdown дополнения
+Перейдите в корень проекта и запустите dev-сервер:

-Тема
-В проекте используется тема material.
+zensical serve

-Для установки запускаем:
-
-`pip install mkdocs-material`
-Полезные ссылки:
-
-Настройки темы material
-Плагины из темы material
-Проект темы material на GitHub
-Плагины
-В проекте используются плагины:
-
-search – встроенный плагин поиска.
-img2fig – отображение картинок в отдельном теге с подписью внизу.
-pip install mkdocs-img2fig-plugin
-
-Для разработки и проверки документации можно использовать команды
-* `mkdocs serve` (с созданием pdf файлов)
-* `mkdocs serve -f dev.yml` (без создания pdf файлов)
-* `mkdocs build -f admin-manuals.yml` (с созданием  pdf файла с инструкциями для администратора)
-
-Перед запуском надо установить mkdocs и его расширения. Сделать это можно при помощи команды, запущенной в папке mkdocs
-```
-pip install -r requirements.txt
-```
-
-Чтобы включить увеличение изображения, необходимо добавить . Если не работает (а это происходит при работе плагина img2fig), то использовать html-вариант. Автоматический конвертер первого варианта во второй (zoom.py) есть в bitedo-doc и документации ERP.
-```
-а) ![Рис 1](examplel.png)
-б) <img alt="Рис 1" src="examplel.png" class="zoom"/>
-```
-
-В случае ошибки **no library called "cairo" was found** необходимо скачать библиотеки:
-
-https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer
-
-https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer/releases
-
-Если при запуске команды **mkdocs serve -f dev.yml** появляется ошибка что данная команда не определена, то в переменнах средах укажите путь: **C:\Users\User\AppData\Roaming\Python\Python310\Scripts**
+Или явно указав конфигурационный файл:

+zensical serve --config-file zensical.toml
@@ -1,55 +1,47 @@
-FROM alpine:3.16 AS builder
+FROM alpine:3.20 AS builder

-ENV MKDOCS_VERSION=1.1.0 \
-    DOCS_DIRECTORY='/mkdocs' \
-    LIVE_RELOAD_SUPPORT='false' \
-    ADD_MODULES='false' \
-    FAST_MODE='false' \
-    PYTHONUNBUFFERED=1 \
-    GIT_REPO='false' \
-    GIT_BRANCH='master' \
-    AUTO_UPDATE='false' \
-    UPDATE_INTERVAL=15
+ENV PYTHONUNBUFFERED=1

-RUN \
-    apk add --update \
+RUN apk add --no-cache \
    ca-certificates \
    bash \
    git \
    openssh \
    python3 \
    python3-dev \
-    py3-setuptools \
-    py-pip \
-    build-base 
-
-ADD docker/container-files/ /
+    py3-pip \
+    build-base \
+    weasyprint

 RUN python -m venv /src/env
-# Enable venv
 ENV PATH="/src/env/bin:$PATH"

-ADD requirements.txt /src/ 
+WORKDIR /src

-RUN \
-    pip install --upgrade pip && \
-    pip install --ignore-installed -r /src/requirements.txt && \
-    cd /bootstrap && pip install -e /bootstrap && \
-    rm -rf /tmp/* /var/tmp/* /var/cache/apk/* /var/cache/distfiles/* && \
-    chmod 600 /root/.ssh/config
+COPY requirements.txt /src/
+RUN pip install --upgrade pip && \
+    pip install -r /src/requirements.txt && \
+    rm -rf /tmp/* /var/cache/apk/*
+
+# Копируем bootstrap, если он у тебя критично нужен
+COPY docker/container-files/ /

-CMD ["/usr/bin/bootstrap", "start"]

 FROM builder as makestatic
-ADD docs /src/docs/
-#ADD overrides /src/overrides/
-ADD mkdocs.yml /src/
-ENV PATH="/src/env/bin:$PATH"

-RUN cd /src  && properdocs build
-#RUN cd /src  && mkdocs build
+COPY docs /src/docs/
+COPY zensical.toml /src/          # новый конфиг
+COPY mkdocs.yml /src/             # оставляем на всякий случай
+COPY custom_theme /src/overrides/ 2>/dev/null || true
+COPY css /src/css/ 2>/dev/null || true
+COPY javascripts /src/javascripts/ 2>/dev/null || true
+
+RUN cd /src && zensical build --config-file zensical.toml
+
+
+FROM nginx:alpine

-FROM nginx
-# RUN rm /etc/nginx/sites-enabled/default
 COPY docker/default.conf /etc/nginx/conf.d/default.conf
-COPY --from=makestatic /src/site /sites/app.lexema.ru/docs
+COPY --from=makestatic /src/site /sites/app.lexema.ru/docs
+
+EXPOSE 80
@@ -0,0 +1,55 @@
+FROM alpine:3.16 AS builder
+
+ENV MKDOCS_VERSION=1.1.0 \
+    DOCS_DIRECTORY='/mkdocs' \
+    LIVE_RELOAD_SUPPORT='false' \
+    ADD_MODULES='false' \
+    FAST_MODE='false' \
+    PYTHONUNBUFFERED=1 \
+    GIT_REPO='false' \
+    GIT_BRANCH='master' \
+    AUTO_UPDATE='false' \
+    UPDATE_INTERVAL=15
+
+RUN \
+    apk add --update \
+    ca-certificates \
+    bash \
+    git \
+    openssh \
+    python3 \
+    python3-dev \
+    py3-setuptools \
+    py-pip \
+    build-base 
+
+ADD docker/container-files/ /
+
+RUN python -m venv /src/env
+# Enable venv
+ENV PATH="/src/env/bin:$PATH"
+
+ADD requirements.txt /src/ 
+
+RUN \
+    pip install --upgrade pip && \
+    pip install --ignore-installed -r /src/requirements.txt && \
+    cd /bootstrap && pip install -e /bootstrap && \
+    rm -rf /tmp/* /var/tmp/* /var/cache/apk/* /var/cache/distfiles/* && \
+    chmod 600 /root/.ssh/config
+
+CMD ["/usr/bin/bootstrap", "start"]
+
+FROM builder as makestatic
+ADD docs /src/docs/
+#ADD overrides /src/overrides/
+ADD mkdocs.yml /src/
+ENV PATH="/src/env/bin:$PATH"
+
+RUN cd /src  && properdocs build
+#RUN cd /src  && mkdocs build
+
+FROM nginx
+# RUN rm /etc/nginx/sites-enabled/default
+COPY docker/default.conf /etc/nginx/conf.d/default.conf
+COPY --from=makestatic /src/site /sites/app.lexema.ru/docs
@@ -0,0 +1,62 @@
+# MkDocs
+## Инструкция по установке есть на сайте MkDocs.
+
+### Надо установить:
+
+python python.org
+pip – менеджер пакет (ставится, обычно, вместе с питоном)
+mkdocs – пакет с движком mkdocs
+
+`pip install mkdocs`
+Полезные ссылки:
+
+mkdocs.org
+
+### плагины MkDocs
+
+Темы MkDocs
+
+markdown дополнения
+
+Тема
+В проекте используется тема material.
+
+Для установки запускаем:
+
+`pip install mkdocs-material`
+Полезные ссылки:
+
+Настройки темы material
+Плагины из темы material
+Проект темы material на GitHub
+Плагины
+В проекте используются плагины:
+
+search – встроенный плагин поиска.
+img2fig – отображение картинок в отдельном теге с подписью внизу.
+pip install mkdocs-img2fig-plugin
+
+Для разработки и проверки документации можно использовать команды
+* `mkdocs serve` (с созданием pdf файлов)
+* `mkdocs serve -f dev.yml` (без создания pdf файлов)
+* `mkdocs build -f admin-manuals.yml` (с созданием  pdf файла с инструкциями для администратора)
+
+Перед запуском надо установить mkdocs и его расширения. Сделать это можно при помощи команды, запущенной в папке mkdocs
+```
+pip install -r requirements.txt
+```
+
+Чтобы включить увеличение изображения, необходимо добавить . Если не работает (а это происходит при работе плагина img2fig), то использовать html-вариант. Автоматический конвертер первого варианта во второй (zoom.py) есть в bitedo-doc и документации ERP.
+```
+а) ![Рис 1](examplel.png)
+б) <img alt="Рис 1" src="examplel.png" class="zoom"/>
+```
+
+В случае ошибки **no library called "cairo" was found** необходимо скачать библиотеки:
+
+https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer
+
+https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer/releases
+
+Если при запуске команды **mkdocs serve -f dev.yml** появляется ошибка что данная команда не определена, то в переменнах средах укажите путь: **C:\Users\User\AppData\Roaming\Python\Python310\Scripts**
+
@@ -1,19 +1,9 @@
-#mkdocs==1.4.0
-properdocs==1.6.7
+zensical
+mkdocs-glightbox==0.4.0
+weasyprint==52.5
+mkdocs-with-pdf
+pymdown-extensions
 mkdocs-literate-nav
 mkdocs-section-index
 mkdocs-include-markdown-plugin
-
-mkdocs-video
-#mkdocs-material==8.5.8
-mkdocs-material>=9.7.5
-mike
-
-weasyprint==52.5
-mkdocs-with-pdf
-
-mkdocs-bootswatch
-
-pymdown-extensions
-
-mkdocs-glightbox==0.4.0
+mkdocs-video
@@ -0,0 +1,19 @@
+#mkdocs==1.4.0
+properdocs==1.6.7
+mkdocs-literate-nav
+mkdocs-section-index
+mkdocs-include-markdown-plugin
+
+mkdocs-video
+#mkdocs-material==8.5.8
+mkdocs-material>=9.7.5
+mike
+
+weasyprint==52.5
+mkdocs-with-pdf
+
+mkdocs-bootswatch
+
+pymdown-extensions
+
+mkdocs-glightbox==0.4.0
@@ -0,0 +1,57 @@
+[project]
+site_name = "Руководство администратора Lexema-ECM"
+site_description = "Официальная документация по администрированию системы Lexema-ECM"
+site_author = "ООО \"Лексема\""
+docs_dir = "docs"
+site_dir = "site"
+
+#  Material
+[project.theme]
+name = "material"
+variant = "classic"
+
+palette.primary = "green"
+palette.accent = "orange"
+
+features = [
+    "navigation.instant",
+    "navigation.top",
+    "navigation.tracking",
+    "toc.follow",
+    "toc.integrate",
+    "navigation.tabs.sticky",
+    "search.suggest",
+    "header.autohide",
+    "navigation.path",
+]
+
+# Markdown extensions
+[project.markdown_extensions]
+toc = { separator = "_", permalink = "#" }
+attr_list = true
+admonition = true
+sane_lists = true
+def_list = true
+
+[project.markdown_extensions.pymdownx.highlight]
+[project.markdown_extensions.pymdownx.superfences]
+[project.markdown_extensions.pymdownx.details]
+[project.markdown_extensions.pymdownx.tabbed]
+alternate_style = true
+
+[project.markdown_extensions.pymdownx.tasklist]
+custom_checkbox = true
+
+# Plugins
+[project.plugins]
+glightbox = { zoomable = true }
+search = { lang = ["ru", "en"] }
+"section-index" = true
+"include-markdown" = true
+"literate-nav" = { nav_file = "SUMMARY.md" }
+
+# DOP
+extra_css = ["css/extra.css"]
+extra_javascript = ["javascripts/extra.js"]
+
+copyright = "© ООО \"Лексема\""