Перейти к содержанию

Цели и задачи проекта

Цель

Познакомиться с принципом Docs as Code и изучить новые инструменты.

Задачи

  1. Создать проект Foliant для документации на языке разметки Markdown.
  2. Генерировать документацию в формате HTML.
  3. Хранить исходники в Git.
  4. Публиковать сайт с документацией на Github.
Дополнительные задачи
  • Описать плагины VS Code.
  • Описать работу с Travis.
  • Описать генерацию PDF и DOCX.
  • Генерировать документы по ГОСТу с помощью GOSTdown.
  • Изменить оформление сайта.
  • Создать задачу в Travis для автоматической публикации документации при Push и Pull Request.
  • Найти инструмент для условий IF PDF - см. Flags.
  • Создать скрипт, который добавляет структуру проекта Foliant в файл build-demo-espd.bat GOSTdown.
  • Протестировать сниппеты;
  • Написать про баг с поиском: не учитываются окончания слов.
  • Интегрировать Swagger.
  • Настроить gitignore.
  • Запустить Foliant через docker.

Используемые инструменты

В проекте используются инструменты:

  • Foliant – инструмент для разработки документации. Позволяет создавать сайты и документы в форматах PDF и DOCX из Markdown-файлов;
  • Python – язык программирования, на котором разработан Foliant;
  • Pandoc – инструмент для конвертации файлов. Используется для создания документов в форматах PDF и DOCX;
  • MiKTeX – открытый дистрибутив TeX для Windows. Используется для настройки и верстки PDF-документов;
  • Mkdocs – генератор статических сайтов;
  • MdToPdf – альтернативная библиотека для создания PDF-документов;
  • GOSTdown – набор шаблонов и скриптов для автоматической вёрстки документов по ГОСТ 19.xxx (ЕСПД) и ГОСТ 7.32 (отчёт о научно-исследовательской работе) в форматах docx из файлов текстовой разметки Markdown;
  • Docker – технология создания контейнеров с открытым исходным кодом, предназначенная для автоматизации развёртывания и управления приложениями. Позволяет «упаковать» приложение со всем его окружением и зависимостями в контейнер;
  • Travis CI – распределённый веб-сервис для сборки и тестирования программного обеспечения, использующий GitHub в качестве хостинга исходного кода.

Процесс разработки

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

  1. Подготовка к работе.
  2. Разработка текстов.
  3. Работа с Git.
  4. Настройка шаблонов сборки, сборка и публикация документации.

Полезные ссылки