diff --git a/README.md b/README.md index 0e59943..c3b99b8 100644 --- a/README.md +++ b/README.md @@ -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) -б) Рис 1 -``` - -В случае ошибки **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 \ No newline at end of file diff --git a/docker/Dockerfile b/docker/Dockerfile index 3f299d3..890765d 100644 --- a/docker/Dockerfile +++ b/docker/Dockerfile @@ -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 \ No newline at end of file +COPY --from=makestatic /src/site /sites/app.lexema.ru/docs + +EXPOSE 80 \ No newline at end of file diff --git a/docker/Dockerfile_old b/docker/Dockerfile_old new file mode 100644 index 0000000..3f299d3 --- /dev/null +++ b/docker/Dockerfile_old @@ -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 \ No newline at end of file diff --git a/readme_old.md b/readme_old.md new file mode 100644 index 0000000..0e59943 --- /dev/null +++ b/readme_old.md @@ -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) +б) Рис 1 +``` + +В случае ошибки **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** + diff --git a/requirements.txt b/requirements.txt index 5623382..5274d73 100644 --- a/requirements.txt +++ b/requirements.txt @@ -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 \ No newline at end of file diff --git a/requirements_old.txt b/requirements_old.txt new file mode 100644 index 0000000..5623382 --- /dev/null +++ b/requirements_old.txt @@ -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 diff --git a/zensical.toml b/zensical.toml new file mode 100644 index 0000000..4b9fca4 --- /dev/null +++ b/zensical.toml @@ -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 = "© ООО \"Лексема\"" \ No newline at end of file