Автоматизируйте вашу документацию с помощью Gitlab и Mkdocs

Производство документации может быть болезненной и потребовать много времени для написания и работы. В этой истории я поделюсь с вами, мой способ генерирования документов с использованием подхода DevOps. Чтобы облегчить жизнь, мы рассмотрим искусство автоматизации 😃.

Пойдем, ребята 😙

Создайте репо

Это просто, следуйте этим шагам:

Войдите в свой Gitlab
Нажмите на новый проект
Дайте ему имя: auto_docs
Инициализировать его с помощью файла readme.md
Сделать это публичным или частным
Ударять Создайте

Теперь клонируйте проект, копировав URL и запустите эту команду: $ git clone https://gitlab.com/auto_docs.git

Настройка среды

Я использую среду Linux, но можно воспроизвести те же шаги на машине Windows. Чтобы следовать за мной, вам нужен набор инструментов, которые должны быть доступны на вашей машине … обязательно установите Python3, у меня есть Python 3.8 (последний).

Создание виртуальной среды

Самый простой способ настроить виртуальную среду – установить пакет VirtualEnv Python, выполняя PIP Install VirtualENV.

Перейдите к местному репозиторию Gitlab и создайте новую виртуальную среду.

$ cd auto_docs/ $ Virtualenv Autodocs $ Source Autodocs/Bin/Activate

Установка материала MKDOCS

Убедитесь, что виртуальная среда активна. Установите материал MKDOCS с помощью этой команды: PIP установить MKDOCS-Material. Этот пакет нуждается в некоторых зависимостях для работы. Установите их, используя Требование.txt Файл, скопируйте список зависимостей в соответствии с требованиями имени файла.txt

Babel==2.8.0
click==7.1.1
future==0.18.2
gitdb==4.0.4
GitPython==3.1.1
htmlmin==0.1.12
Jinja2==2.11.2
joblib==0.14.1
jsmin==2.2.2
livereload==2.6.1
lunr==0.5.6
Markdown==3.2.1
MarkupSafe==1.1.1
mkdocs==1.1
mkdocs-awesome-pages-plugin==2.2.1
mkdocs-git-revision-date-localized-plugin==0.5.0
mkdocs-material==5.1.1
mkdocs-material-extensions==1.0b1
mkdocs-minify-plugin==0.3.0
nltk==3.5
Pygments==2.6.1
pymdown-extensions==7.0
pytz==2019.3
PyYAML==5.3.1
regex==2020.4.4
six==1.14.0
smmap==3.0.2
tornado==6.0.4
tqdm==4.45.0

Установите их все с одной командой: PIP установка -R Требования.txt

Теперь пришло время создать новый проект MKDOCS 😅.

Запустите эту команду: Mkdocs new Анкет и убедитесь, что у вас есть эта структура:

|--auto_docs
    |--- docs
    |--- mkdocs.yml

Документы Папка содержит структуру вашей документации, она содержит подпапки и файлы разметки.
mkdocs.yml Файл определяет конфигурацию сгенерированного сайта. Давайте проверим установку, выполнив эту команду: MKDOCS обслуживает. Сайт будет доступен на http://locahost: 8000 И вы должны увидеть первоначальный вид документов.

Настройка CI/CD

Давайте позволите LE CI/CD автоматизировать сборку и развертывание документов. Обратите внимание, что Gitlab предлагает функцию под названием Gitlab Pages, которая может бесплатно обслуживать статический ресурс (HTML, JS, CSS). Путь репо преобразуется в URL в ваши документы.

Создать файл CI/CD

Gitlab использует файл YAML – он содержит конфигурацию трубопровода. Содержание файла CI:

stages :
  - build
pages:
  stage: build
  image:
  name: squidfunk/mkdocs-material
  entrypoint:
    - ""
  script:
    - mkdocs build
    - mv site public
  artifacts:
    paths:
      - public
  only:
    - master
  tags:
    - gitlab-org-docker

В этом трубопроводе используется исполнителя Docker с изображением, которое содержит уже установленные MKDOCS… MKDOCS создает проект и поместите активы сборки на папку, называемую сайтом … чтобы иметь возможность использовать страницы Gitlab, вы должны назвать свои страницы задания и вставить активы на сайте Новая папка под названием Public. Для тегов: проверьте раздел бегуна в разделе «Настройки» → CI/CD → Runners и выберите одного из общих бегунов, у которых есть тег Gitlab-Org-Docker. Все было сделано 🎉 😸 😸!

Ой ! Просто одна вещь … мы забыли файлы виртуальной среды .. Они большие и не нужны на трубопроводе … они только для местного развития. Изображение MKDOCS на трубопроводе уже поставляется с необходимыми пакетами. Итак … создайте новый файл с именем .gitignore и добавьте эти строки:

auto_docs/ 
requirements.txt

Папка Auto_DOCS имеет то же имя, что и в виртуальной среде .. не забудьте 😠! Вы будете наказаны, нажимая +100mi 😝, и вы будете ждать всю свою жизнь, чтобы завершить процесс, ха -ха 😢.

Теперь беги git add. && git commit -m "Первоначальный коммит" a && git push … Перейдите в свой репозиточный репо и нажмите CI/CD → COBLINES, нажмите на синий значок и визуализируйте журналы. Как только задание будет успешна, перейдите к настройкам -> Страницы и нажмите на ссылку на свой новый сайт документации (вы должны ждать Для доступности 10 млн.

Наконец, я надеюсь, что это было полезно! Спасибо за чтение 😺 😍!

Оригинал: “https://dev.to/hatembentayeb/automate-your-documentation-with-gitlab-and-mkdocs-2blf”