docs/ecm-administrator-manuals
5
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

upd

Browse Source
This commit is contained in:
jukov_mn
2026-06-05 11:37:27 +05:00
parent af66306db0
commit 92be7b9965
7 changed files with 238 additions and 104 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+11 -52
View File
@@ -1,62 +1,21 @@
# MkDocs
## Инструкция по установке есть на сайте MkDocs.
### Надо установить: # Разработка документации (Zensical)
python python.org ## Локальная разработка с live-превью
pip – менеджер пакет (ставится, обычно, вместе с питоном)
mkdocs – пакет с движком mkdocs
`pip install mkdocs` **Zensical** имеет встроенный dev-сервер с **live-reload** — это полноценная и более быстрая замена старой команде `mkdocs serve`.
Полезные ссылки:
mkdocs.org ### Как запустить
### плагины MkDocs 1. Установите Zensical:
Темы MkDocs ```bash
pip install zensical
markdown дополнения Перейдите в корень проекта и запустите dev-сервер:
Тема zensical serve
В проекте используется тема 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**
zensical serve --config-file zensical.toml
docker/Dockerfile
+28 -36
View File
@@ -1,55 +1,47 @@
FROM alpine:3.16 AS builder FROM alpine:3.20 AS builder
ENV MKDOCS_VERSION=1.1.0 \ ENV PYTHONUNBUFFERED=1
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 \ RUN apk add --no-cache \
apk add --update \
ca-certificates \ ca-certificates \
bash \ bash \
git \ git \
openssh \ openssh \
python3 \ python3 \
python3-dev \ python3-dev \
py3-setuptools \ py3-pip \
py-pip \ build-base \
build-base weasyprint
ADD docker/container-files/ /
RUN python -m venv /src/env RUN python -m venv /src/env
# Enable venv
ENV PATH="/src/env/bin:$PATH" ENV PATH="/src/env/bin:$PATH"
ADD requirements.txt /src/ WORKDIR /src
RUN \ COPY requirements.txt /src/
pip install --upgrade pip && \ RUN pip install --upgrade pip && \
pip install --ignore-installed -r /src/requirements.txt && \ pip install -r /src/requirements.txt && \
cd /bootstrap && pip install -e /bootstrap && \ rm -rf /tmp/* /var/cache/apk/*
rm -rf /tmp/* /var/tmp/* /var/cache/apk/* /var/cache/distfiles/* && \
chmod 600 /root/.ssh/config # Копируем bootstrap, если он у тебя критично нужен
COPY docker/container-files/ /
CMD ["/usr/bin/bootstrap", "start"]
FROM builder as makestatic 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 COPY docs /src/docs/
#RUN cd /src && mkdocs build 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 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
docker/Dockerfile_old
+55
View File
@@ -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
readme_old.md
+62
View File
@@ -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**
requirements.txt
+6 -16
View File
@@ -1,19 +1,9 @@
#mkdocs==1.4.0 zensical
properdocs==1.6.7 mkdocs-glightbox==0.4.0
weasyprint==52.5
mkdocs-with-pdf
pymdown-extensions
mkdocs-literate-nav mkdocs-literate-nav
mkdocs-section-index mkdocs-section-index
mkdocs-include-markdown-plugin mkdocs-include-markdown-plugin
mkdocs-video
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
requirements_old.txt
+19
View File
@@ -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
zensical.toml
+57
View File
@@ -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 = "© ООО \"Лексема\""