Рубрики
Без рубрики

Документация упрощает с Mkdocs и Gitlab Pages

Обзор Я создал статический веб -сайт с использованием MKDOCS и развернулся на страницах Gitlab. Это то, что… Tagged with Gitlab, Mkdoc, Python, Tulciory.

Обзор

Я создал статический веб -сайт, используя Mkdocs и развернуто в Гитлаб Страницы Анкет Это то, что я сделал: https://bemn-proof-of-concept.gitlab.io/mkdoc/ Анкет

Таблица содержания

  • Mkdocs
    • Подготовка
    • Вверх и беги
    • Добавить новую страницу
    • Темация
    • Пользовательские ресурсы
  • Гитлаб Страницы
    • .gitlab-ci.yml
    • Стройте и разверните
  • Вывод

Mkdocs

От Официальный сайт MKDOCS :

MKDOCS – это быстро , Простой и совершенно великолепно Статический генератор сайта, который ориентирован на строительство документации проекта. Исходные файлы документации записаны в Markdown и настроены с одним файлом конфигурации YAML.

На мой взгляд, настройка статического сайта с использованием MKDOCS действительно проста. Легко изменить тему и вставить пользовательские стили/сценарии. Держите это простым, глупым Анкет Это то что мне нужно.

Подготовка

Убедитесь, что у вас есть следующие инструменты:

  1. Python 3.x и пип . Установите его через исполняемый файл с официального веб -сайта или использование таких инструментов, как Homebrew Анкет
$ python --version
Python 3.8.2
$ pip --version
pip 20.0.2 from /usr/local/lib/python3.8/site-packages/pip (python 3.8)

  1. A Gitlab учетная запись. Вы можете использовать другие услуги, такие как GitHub Pages , Amazon S3 и т. Д.
  2. (необязательно) Чистовый лист Marckdown .

(Для меня самая сложная часть – как правильно поднять версии Python и Pip. В Mac встроенная версия Python составляет 2,7, но нам нужен Python 3, чтобы установить Pip ..

Вверх и беги

$ pip install mkdocs
$ mkdocs --version
mkdocs, version 1.1.2

Предполагая, что ваша папка проекта Doc-Project :

$ mkdocs new doc-project
$ cd doc-project

Затем создается проект MKDOCS с помощью следующей структуры папок:

doc-project
├── docs
│   └── index.md
├── img
│   └── favicon.ico
└── mkdocs.yml

Давайте запустим сайт:

$ mkdocs serve
INFO - Building documentation...
INFO - Cleaning site directory
INFO - Documentation built in 1.65 seconds
[I 200612 23:30:19 server:334] Serving on http://127.0.0.1:8000

И проверьте это в http://127.0.0.1:8000 !

Добавить новую страницу

Содержимое

Помните, что все документы должны разместить под док . Давайте создадим обзорную страницу:

$ cd docs
$ touch overview.md

После этого добавьте немного контента в Обзор.md Анкет

Меню

Если вы хотите, чтобы посетители достигли страницы обзора, вам нужно добавить URL в меню. Давайте редактировать mkdocs.yml , файл конфигурации сайта:

# In mkdocs.yml...
site_name: Doc Project ## change your site name here.
nav:
  - Home: index.md
  - Overview: overview.md ## add this line.

Вы увидите новую ссылку под названием Обзор в меню. Если вы хотите установить имя своего сайта сейчас, измените значение site_name Анкет

Ну это все. Вот как добавить новую страницу.

Темация

Вы можете применить индивидуальную тему к MKDOCS. Эта страница Содержит множество тем, предоставленных сообществом.

В этом разделе я применю Тема дизайна материала на мой сайт MKDOCS.

Прекратите запускать свой сайт и установить тему на:

$ pip install mkdocs-material

Обновите mkdocs.yml очередной раз:

# In mkdocs.yml...
site_name: Doc Project

nav:
  - Home: index.md
  - Overview: overview.md

## Add this section
theme:
  name: material
  palette: ## Add this sub-section if you want to change the theme color
    scheme: amber
    primary: amber
    accent: orange

Начните сайт:

$ mkdocs serve

Вы увидите, что MKDOCS одевает тему дизайна материала янтарного материала.

Пользовательские ресурсы

Иногда вы можете добавить пользовательские CSS или JS. В MKDOCS вы можете сделать это, добавив extra_css и extra_javascript разделы в mkdocs.yml Анкет

Я создал Каталог Страница, которая содержит таблицу, написанную в Markdown. Также я хочу подать заявку jQuery DataTables Чтобы сделать стол более интерактивным. Поэтому я добавил связанные библиотеки JS и соответствующий файл CSS в MKDOCS. Вы можете увидеть результат Здесь Анкет

Использование: Создать Catalog.md Файл и добавьте в него таблицу разметки.

Далее добавьте разделы пользовательских ресурсов в файл конфигурации:

# In mkdocs.yml...
site_name: Doc Project
nav:
  - Home: index.md
  - Catalog: catalog.md ## The catalog page you created in the exercise.

theme:
  name: material
  palette:
    scheme: amber
    primary: amber
    accent: orange

## Custom js files.
extra_javascript:
  - https://code.jquery.com/jquery-3.5.1.min.js
  - https://cdn.datatables.net/1.10.21/js/jquery.dataTables.min.js
  - scripts/site.js

## Custom css files.
extra_css:
  - https://cdn.datatables.net/1.10.21/css/jquery.dataTables.min.css

Создайте пользовательский файл JS:

$ cd docs
$ mkdir scripts
$ cd scripts
$ touch site.js

Теперь в твоем site.js файл:

$(document).ready( function () {
    $('table').DataTable();
});

Что еще, вы сможете увидеть интерактивную таблицу на странице каталога.

Гитлаб Страницы

Создайте репозиторий Gitlab под вашим личным пространством или проектной группой. URL будет чем -то вроде https://gitlab.com/bername или имя группы проекта}/{repo name} Анкет

Клонировать создание репо и создайте следующие элементы:

$ mkdir src
$ touch .gitlab-ci.yml

Поместите свои элементы MKDOC (то есть Doc-Project Папка) под SRC Анкет Смотрите следующую структуру папки:

(root of the repo)
├── .gitlab-ci.yml
└── src
    └── doc-project

.gitlab-ci.yml

.gitlab-ci.yml является специфичным для Gitlab файл. Gitlab будет читать и запустить шаги в файле. Нам нужно сообщить Гитлабу, как генерировать и развернуть наш статический веб -сайт MKDOCS. В этом файле:

# In .gitlab-ci.yml...
image: python:3.8-buster ## MkDocs requies python.

pages:
  stage: deploy ## tell GitLab to deploy the website in this step.
  before_script:
    - pip install mkdocs ## install MkDocs.
    - pip install mkdocs-material ## install the theme.
  script:
    - cd ./src/doc-project
    - mkdocs build ## built the site.
    - mv site ../../public
  artifacts:
    paths:
    - public
  ## Uncomment the following section if you want to run this step under master branch only.
  # only:
  # - master 

Таким образом, в основном он говорит Gitlab установить инструменты, необходимые в среде Python 3.8, и развернуть веб -сайт после создания сайта.

Попробуйте запустить следующую команду, если вы хотите создать сайт локально:

$ mkdocs build

Сгенерированный сайт расположен под doc-project/site/ Анкет

Чтобы правильно отобразить веб -сайт, вам необходимо разместить сгенерированный сайт под public Папка и пусть Гитлаб знает Артефакт Внутри сайт, который вы хотите развернуть.

Стройте и разверните

Нажмите код в Gitlab, и сайт должен создавать автоматически. Проверьте статус сборки под CI/CD -> Трубопроводы Анкет

Зеленая метка, показывающая, прошел для каждого успешного строительства.

Проверьте свой сайт сейчас. URL https://{Имя пользователя или имя группы проекта} .gitlab.io/{repo name}/ .

Вывод

В этом уроке мы создали статический сайт с пользовательской темой, стилями и библиотекой JS с помощью MKDOCS. После этого мы установили трубопровод CI/CD на Gitlab для строительства и развертывания этого статического сайта на страницы Gitlab.

Оригинал: “https://dev.to/bemnlam/documentation-makes-easy-with-mkdocs-and-gitlab-pages-27e8”