Документация для разработки с EdgeX-Docs

Локальная разработка (docker) (рекомендуется)

Чаще всего локальную разработку edgex-docs используют для проверки изменений в HTML. Чтобы упростить проверку документации, можно выполнить следующую команду:

make serve

После запуска вы можете просматривать обработанный контент локально и вносить изменения в документацию, просматривая их в реальном времени в браузере по адресу:
http://localhost:8008

Если вы хотите только проверить успешность сборки документации, выполните следующую команду:

make build

По завершении работы можно очистить систему с помощью команды:

make clean

Локальная разработка (native)

Чтобы отобразить и просмотреть сайт локально (без docker), вам потребуется несколько вещей для начала работы.

1. Вам необходимо установить Python и pip.
2. После установки Python вам понадобятся следующие зависимости Python:

pip install mkdocs pip install mkdocs-material==8.2.1

3. После того как все предварительные требования будут установлены, вы можете просто запустить mkdocs serve и просматривать обработанный контент локально, а также вносить изменения в свою документацию и просматривать их в режиме реального времени в браузере на http://0.0.0.0:8001/edgex-docs.

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

Чтобы проверить, что все ссылки в наборе документации действительны:

1. Установите плагин htmlproofer (только native):

   Примечание: при использовании метода docker он уже установлен в образе.

   pip install mkdocs-htmlproofer-plugin

2. Экспортируйте переменную среды ENABLED_HTMLPROOFER.

   Обратите внимание: это добавляет около 5 минут каждый раз, когда вносятся изменения, поэтому рекомендуется делать это после внесения всех изменений.

   export ENABLED_HTMLPROOFER=true

3. Выполните make build или make serve. Неработающие ссылки будут перечислены в конце процесса сборки.

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

«Публикация» ваших изменений

Публикация осуществляется через конвейер Jenkins. Как только PR будет объединён, изменения будут отражены на сайте документации, размещённом в ветке gh-pages и обслуживаемом страницами Github.

Различные версии документации хранятся в отдельных ветках. Ветка main содержит исходные файлы для разрабатываемой версии, а также следующие файлы производственного сайта:

• docs/CNAME — запись DNS, которая сообщает страницам Github обслуживать контент по адресу https://docs.edgexfoundry.org вместо https://edgexfoundry.github.io/edgex-docs
• docs/index.html — индексная страница сайта, которая перенаправляет с / на /{latest-release}
• docs/versions.json — информация о версии для заполнения выпадающего меню версии сайта

Конвейер копирует файлы в отдельные каталоги внутри ветки gh-pages. Например, когда версия разработки — 2.2:

Другие файлы, такие как файлы для проверок CI и руководства, также копируются из всех веток.

Версионирование документов

Когда выпускается новая версия EdgeX, мы также версируем документы. Для этого необходимо выполнить четыре шага:

1. Создать ветку без файлов производственного сайта

   i) Создайте ветку из main для выпущенной документации. Имя ветки должно совпадать с именем новой версии EdgeX. Например, для версии 2.2 создаётся ветка kamakura.

   ii) Удалите файлы производственного сайта из ветки, перечисленные [здесь](#публикация ваших изменений). Это необходимо сделать, чтобы избежать переопределения производственных файлов; см. #680.

2. Добавьте версию, которая будет добавлена в файл docs/versions.json. Этот файл заполнит раскрывающийся список на сайте, развёрнутом по адресу https://docs.edgexfoundry.org

[
    {"version": "1.1", "title": "1.1-Fuji", "aliases": []},
    {"version": "1.2", "title": "1.2-Geneva", "aliases": []}
    {"version": "[новый номер версии здесь]", "title": "[название, которое отображается в раскрывающемся списке]", "aliases": []}
]

3. Значение, помещённое в свойство version выше, ДОЛЖНО соответствовать имени папки, содержащей версионное содержимое в ветке gh-pages. Это указывается путём обновления свойства site_dir: в файле mkdocs.yml:

site_name: Документация EdgeX Foundry
docs_dir: ./docs_src
site_dir: ./docs/1.2 #ОБНОВИТЕ НОМЕР ВЕРСИИ ЗДЕСЬ В СООТВЕТСТВИИ С ТЕМ, ЧТО НАХОДИТСЯ В VERSION.JSON
site_description: 'Документация по использованию EdgeX Foundry'
site_author: 'Michael Johanson'
site_url: 'https://edgexfoundry.github.io/edgex-docs/'
repo_url: 'https://github.com/edgexfoundry/edgex-go'
repo_name: 'edgex/edgex-go'
copyright: 'Copyright © 2020 EdgeX Foundry'
...

Как только это будет сделано и объединено, задание сборки разместит контент в указанной папке в ветке gh-pages.

4. Обновите docs/index.html, чтобы перенаправить с / на самый последний каталог выпуска. Например, если последняя версия — 2.1:

<!DOCTYPE html>
<html>
<head>
<title>Перенаправление</title>
<script>
    window.location.replace("2.1"); //ОБНОВИТЬ МЕНЯ
</script>
</head>
<body>
</body>
</html>