Автономное программное обеспечение для создания статической HTML-документации из Markdown.

Я ищу инструмент, который может генерировать статические HTML-страницы из файлов уценки. Пока все хорошо, их много:

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

  • Разработчик запускает свою рабочую станцию ​​(Стандартная Windows 7)
  • Разработчик проверяет репозиторий (содержащий файлы уценки и инструмент для создания)
  • Разработчик запускает генерацию документов, скажем, по телефонуcreateDocs.bat
  • Разработчик открывает сгенерированный index.html в своем браузере.

Теперь моя проблема заключается в том, что для всех вышеупомянутых инструментов требуется заранее настроенная среда: node.js, Python и дополнительные модули, ... Однако идея автономной среды заключается в том,

  • Он работает на оффлайн хостах
  • Он работает на хостах, где невозможно установить программное обеспечение.
  • Он работает за корпоративным прокси

Кто-нибудь знает хороший инструмент, который будет работать таким образом? Есть ли способы заставить вышеупомянутые инструменты работать? Я только что пробовал много вещей, таких как преобразование mkdocs с помощью py2exe, но не добился успеха...

Почему он работает на хостах, где невозможно установить программное обеспечение ? Вы использовали слово «Разработчик»; предположительно, он имеет некоторый контроль над своей машиной и может «установить программное обеспечение», вы даже настаиваете, чтобы он мог «проверить репозиторий», что означает, что у него должно быть (на практике) установленное программное обеспечение для управления версиями.

Ответы (2)

Доксиген

Doxygen — это инструмент документирования кода общего назначения. Он поддерживает Markdown, начиная с версии 1.8.0 , и может генерировать статические HTML-файлы среди многих других форматов.

Функции:

  • Кроссплатформенность. Работает на всех версиях Windows, начиная с XP.
  • Имеет портативную установку, которую вы можете связать с вашим репозиторием, чтобы она работала в автономном режиме и без прав администратора:

Требуемый рабочий процесс может быть легко достигнут с помощью doxygen:

С большинством систем контроля версий очень плохая идея проверять двоичные файлы - в сети много дискуссий о том, почему, но в основном, если это не исходный код, он не принадлежит системе контроля версий.
@SteveBarnes Верно. В этом случае достаточно проверить конфигурацию и пакетные файлы, так как любой может загрузить и запустить исполняемый файл с веб-сайта Doxygen.
В моем понимании неплохо проверять бинарники как таковые. Это просто проблема, если у вас также есть исходники (тогда это избыточно). В случае с doxygen или другой третьей стороной это хороший способ гарантировать, что среда, в которой создается программное обеспечение, останется прежней.
@MONsDaR Определенно нет никаких правил против этого. Я думаю, что большинство аргументов утверждают, что, поскольку вы не можете использовать инструменты VC (например, diff) для двоичных файлов, нет смысла их версионировать. Но в вашем случае я думаю, что удобство наличия исполняемого файла по определенному пути является достаточно веской причиной для его включения.
Некоторые (многие) системы VCS становятся очень медленными и громоздкими, когда в них хранятся двоичные файлы. Мой предпочтительный подход состоит в том, чтобы иметь известное место, где хранится одна или несколько конкретных версий входных двоичных файлов, и скрипт с контролем версий, который извлекает требуемая версия. Это по-прежнему двухэтапный процесс - обновление из VCS, затем создание (точно так же, как если бы инструмент был в VCS). вы можете привязать конкретную версию инструмента к данной версии вашего источника и т. д. Также в компании, в которой я работаю, есть специальное правило против этого.
Это обсуждение немного уходит от исходного вопроса, извините за это. @Steve: Если вы храните двоичные файлы на сервере и создаете пользовательский скрипт, который выбирает правильную версию, разве вы не просто вручную перестраиваете то, для чего предназначена VCS? Как узнать, какие бинарные файлы подходят к какой ревизии? Как вы можете гарантировать, что у конкретной версии есть нужные двоичные файлы на сайте? Вот некоторые из самых больших проблем, с которыми я столкнулся: 1. Настройка правильной среды, прежде чем можно будет что-то сделать. 2. Воспроизведение того, что когда-то работало с определенной сторонней версией.

Я могу предложить вам несколько вариантов:

Автономные двоичные файлы

  1. Переносимый Python . Вам, вероятно, потребуется выбрать один из вышеперечисленных генераторов документов или, возможно , Sphinx и добавить его в свою портативную «установку» Python.
  2. Pandoc создан как перемещаемый двоичный файл, как описано здесь .

Оба вышеперечисленных отвечают требованиям:

  • Он работает на оффлайн хостах
  • Он работает на хостах, где невозможно установить программное обеспечение.
  • Он работает за корпоративным прокси

Но в любом из вышеперечисленных случаев я бы настоятельно рекомендовал изменить желаемый рабочий процесс, добавив шаг «разработчик загружает и распаковывает инструмент», поскольку есть много причин не помещать двоичные файлы в системы контроля версий, а многие корпоративные СКВ имеют определенные политики. чтобы помешать вам сделать это.

Сервер внутри брандмауэра

Другим вариантом может быть создание онлайн-сервера генерации документов, но за корпоративным брандмауэром. Это не будет работать в автономном режиме, но обеспечит гораздо больший контроль над тем, какое программное обеспечение используется, его также можно интегрировать с VCS через хуки, чтобы рабочий процесс был изменен на:

  • Разработчик запускает свою рабочую станцию
  • Разработчик Проверяет репозиторий — для этого он должен быть в сети .
  • Хук после проверки отправляет уценку на сервер генератора документов, пока они все еще находятся в сети , что создает html на их локальном диске.
  • Разработчик вносит изменения в уценку — это можно сделать в автономном режиме .
  • Разработчик генерирует html из измененной уценки, чтобы проверить свою работу - для этого либо нужно быть в сети, либо иметь локальную установку того же инструмента.
  • Разработчик снова фиксирует изменения, для этого в любом случае нужно быть в сети.

Это не соответствует вашему первому требованию, но дает некоторые преимущества:

  • Вы можете использовать практически любой инструмент, который вам нужен
  • Нет проблем с инструментами контроля версий
  • Не все ваши разработчики должны работать под управлением Windows
  • Ваш генератор документов может иметь доступ к ресурсам, которые вы, возможно, не хотите устанавливать на машине разработчика, например, html может включать отчеты, сгенерированные вашей системой отслеживания проблем или системой отчетов о ходе работы.
Я уже думал о настройке сервера для генерации документации. Оба метода имеют свои преимущества. Обсудим это завтра.
Автономное программное обеспечение для создания статической HTML-документации из Markdown.
СпросиСетьПолитика конфиденциальности1y, 0v