Не уверен, что это должно быть здесь или Программисты.
Создание документов API
Я хотел бы получить несколько советов о том, как я должен создавать документацию API для внутреннего проекта. Я относительно новичок в Git, и мы пытаемся внедрить некоторые методы сборки/развертывания звука.
Одна из вещей, которые мы обсуждали, заключалась в том, чтобы убедиться, что наша база кода хорошо документирована и генерирует документацию с использованием чего-то вроде PhpDocumentor2 или одного из многих подобных инструментов.
Мы начали реализовывать рабочий процесс, похожий на один подробный здесь.
Должен ли я автоматизировать процесс создания документов?
Например, pre или post commit hook в Git при пометке выпуска. Или должен ли я, когда я объединиться, перейти к ветки релиза, просто вручную создать документы и зафиксировать в репозитории?
Является ли стандартной практикой создание документов для каждой версии?
Возможно, я неправильно понял этот процесс, если новый выпуск документа коррелирует с релизом/тегом Git?
Где хранятся сгенерированные документы?
В том же репозитории? другой репозиторий? Хостинг где-то вроде Прочитать Документы или только внутренне? Текущий проект, над которым мы работаем, является лишь небольшим, но в случае успеха мы хотели бы продолжить процесс в других крупных проектах в будущем.
Контекст
Проект представляет собой расширение Magento, которое мы хотели бы предоставить API-документы, модульное тестирование и соответствующий PSR-код. Мне не хватает информации о том, как интегрируется весь рабочий процесс. PHPunit и PHPDocumentor2 устанавливаются локально через Composer.
Я слышал и смотрел на Трэвиса Ки, но я не уверен, что Docs попадают в эту категорию.
Этот вопрос может показаться мелким и/или тривиальным, однако у меня мало опыта интеграции и рабочего процесса Git, и я не мог найти много информации.
