Создание документов API в Git Workflow

Не уверен, что это должно быть здесь или Программисты.

Создание документов API

Я хотел бы получить несколько советов о том, как я должен создавать документацию API для внутреннего проекта. Я относительно новичок в Git, и мы пытаемся внедрить некоторые методы сборки/развертывания звука.

Одна из вещей, которые мы обсуждали, заключалась в том, чтобы убедиться, что наша база кода хорошо документирована и генерирует документацию с использованием чего-то вроде PhpDocumentor2 или одного из многих подобных инструментов.

Мы начали реализовывать рабочий процесс, похожий на один подробный здесь.


Должен ли я автоматизировать процесс создания документов?

Например, pre или post commit hook в Git при пометке выпуска. Или должен ли я, когда я объединиться, перейти к ветки релиза, просто вручную создать документы и зафиксировать в репозитории?

Является ли стандартной практикой создание документов для каждой версии?

Возможно, я неправильно понял этот процесс, если новый выпуск документа коррелирует с релизом/тегом Git?

Где хранятся сгенерированные документы?

В том же репозитории? другой репозиторий? Хостинг где-то вроде Прочитать Документы или только внутренне? Текущий проект, над которым мы работаем, является лишь небольшим, но в случае успеха мы хотели бы продолжить процесс в других крупных проектах в будущем.

Контекст

Проект представляет собой расширение Magento, которое мы хотели бы предоставить API-документы, модульное тестирование и соответствующий PSR-код. Мне не хватает информации о том, как интегрируется весь рабочий процесс. PHPunit и PHPDocumentor2 устанавливаются локально через Composer.

Я слышал и смотрел на Трэвиса Ки, но я не уверен, что Docs попадают в эту категорию.

Этот вопрос может показаться мелким и/или тривиальным, однако у меня мало опыта интеграции и рабочего процесса Git, и я не мог найти много информации.

Ответ 1

Сгенерированные документированные обычно:

  • всегда синхронизируется с источником кода (так что вопрос о том, должен ли новый выпуск документа коррелировать с git release/тегом "становится спорным)
  • не сохраняется в ссылочном файле управления версиями (например, git repo), а скорее (повторно) генерируется по желанию (в любом месте, которое вам нравится).

Если вы посмотрите на проект с большим источником кода и обширную документацию по коду, вы можете взять в качестве примера язык Go и его репозиторий (Mercurial repo, но у вас есть зеркало на GitHub, а также)