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

49

Когда вы используете такие инструменты, как jsdocs , он генерирует статические HTML-файлы и их стили в вашей кодовой базе на основе комментариев в вашем коде.

Должны ли эти файлы быть добавлены в репозиторий Git или их следует игнорировать с помощью .gitignore?

git documentation

— вывоз мусора
источник

4

Может быть аргумент для сохранения их в репозитории GitHub, так как вы можете публиковать статический HTML, используя страницы . Хотя тогда возникает совершенно отдельный набор аргументов о том, как вы обеспечиваете их актуальность и т. Д.

— Борис Паук

21

Если файлы генерируются, то по определению они не являются исходными .

— Хрилис - на забастовку -

3

Вы публикуете то, что хотите опубликовать. Особенно на GitHub. Если вы хотите, чтобы все увидели сгенерированный PDF или изображение, вы должны включить его, вместо того чтобы ожидать, что все установят LaTeX и скомпилируют его сами. Например, этот репозиторий был бы не очень хорош, если бы он не включал созданные изображения, только файлы проекта ...

— Джурис

5

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

— комнат

7

Как потребитель сторонних библиотек, из 10 раз, когда я вижу библиотеку без онлайновой документации (будь то в подпапке репозитория или связанной с файлом readme), я щелкаю и пропускаю эти библиотеки все 10 раз , Я не собираюсь возиться с Doxygen в течение получаса, просто чтобы посмотреть, отвечает ли библиотека моим потребностям.

— Александр

131

При отсутствии какой-либо конкретной необходимости, любой файл, который может быть собран, воссоздан, сконструирован или сгенерирован из инструментов сборки с использованием других файлов, отмеченных в управлении версиями, не должен быть возвращен. Когда файл необходим, он может быть (повторно) собран из другого исходники (и, как правило, будут как некоторые аспекты процесса сборки).

Поэтому эти файлы следует игнорировать с помощью .gitignore.

— 1201ProgramAlarm
источник

4

Но это может зависеть от версий инструментов сборки или даже от доступности инструментов сборки (например, для генерации некоторых файлов требуется старая версия инструмента сборки). Как вы справляетесь с этим? Можете ли вы указать это в своем ответе?

— Питер Мортенсен

27

@PeterMortensen Если вам нужен артефакт, созданный с помощью специальной версии инструментов buld, вы создаете его с помощью необходимой вам версии инструментов сборки. Такая необходимость либо: а) обнаружена вами самостоятельно, и в этом случае вы сами; б) документировано в README («Вам понадобится две, на которых установлены 2 конкретные версии doxygen ...»); c) обрабатываются сценариями сборки (они проверяют доступные версии инструментов сборки и действуют соответствующим образом). В любом случае исходный контроль предназначен для источников, а не для артефактов сборки.

— Joker_vD

2

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

— Александр

4

@Alexander Вы бы также поместили встроенный бинарный файл в репо? Документация построена. Вы берете собранную документацию и делаете ее доступной где-нибудь.

— 1201ProgramAlarm

5

@ 1201ProgramAlarm "Вы бы также поместили встроенный бинарный файл в репо?" Нет, потому что встроенный двоичный файл имеет низкую начальную стоимость для людей, просматривающих GitHub, по сравнению с документацией. «Вы берете встроенную документацию и делаете ее доступной где-нибудь». Пока это общедоступно, явно связано, да, это здорово. Это, наверное, лучший случай.

— Александр

23

Мое правило таково: когда я клонирую репозиторий и нажимаю кнопку «сборки», через некоторое время все строится. Чтобы добиться этого для сгенерированной документации, у вас есть два варианта: либо кто-то отвечает за создание этих документов и их размещение в git, либо вы документируете, какое именно программное обеспечение мне нужно на моей машине для разработки, и вы нажимаете «build» Кнопка строит всю документацию на моей машине.

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

@ Курт Симпсон: Документирование всех требований к программному обеспечению намного лучше, чем я видел во многих местах.

— gnasher729
источник

7

Не документируйте, какое программное обеспечение нужно для сборки (или, по крайней мере, не просто документируйте): заставьте скрипт сборки сообщить пользователю, что ему не хватает, или даже установить его самостоятельно, если это разумно. В большинстве моих репозиториев любой наполовину компетентный разработчик может просто запустить ./Testи получить сборку или получить хорошую информацию о том, что ему нужно сделать, чтобы получить сборку.

— Курт Дж. Сэмпсон

5

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

— Султан

Это ваше правило, и это хорошее правило, и мне это нравится. Но другие могут устанавливать свои собственные правила.

— Эмори

Я думаю, что вы имеете в виду «запустить команду сборки», поскольку на вашем компьютере не будет кнопки сборки. ... Если вы не ожидаете, что вся сборка будет интегрирована с IDE, что совершенно неразумно.

— jpmc26

@ jpmc26 Я считаю совершенно разумным интегрировать всю сборку в IDE. Кнопка сборки на моей машине - Command-B.

— gnasher729

14

Эти файлы не должны быть возвращены, потому что данные для их создания уже присутствуют. Вы не хотите хранить данные дважды (СУХОЙ).

Если у вас есть система CI, вы можете создать документацию и сохранить ее для этой сборки / опубликовать ее на веб-сервере.

— Tvde1
источник

4

Одно из преимуществ наличия их в каком-либо репозитории (либо в том же, либо в другом, предпочтительно автоматически сгенерированном) состоит в том, что тогда вы можете видеть все изменения в документации. Иногда эти различия легче читать, чем различия в исходном коде (особенно если вы заботитесь только об изменениях спецификации, а не о реализации).

Но в большинстве случаев их не нужно контролировать в исходном коде, как объяснили другие ответы.

— Пауло Эберманн
источник

1

Это в значительной степени потребует ловушки перед фиксацией в каждом репо, который используется для создания коммитов. Потому что, если процесс создания документации не полностью автоматизирован, вы получите коммиты, у которых документация не синхронизирована с кодом. И эти нарушенные коммиты повредят понятности больше, чем незафиксированная документация.

— cmaster

1

Это не должно быть на этапе фиксации. Это может быть простой задачей / CI / Jenkins - публиковать их каждый раз, когда они считаются достойными хранения. Это может быть каждый коммит, но решение должно быть отделено при отсутствии веской причины. Или, по крайней мере, так я это вижу.

— ANone

3

Игнорируется. Вы захотите, чтобы пользователи репо могли их перестроить в любом случае, и это устраняет сложность уверенности в том, что документы всегда синхронизированы. Нет причин не собирать собранные артефакты в одном месте, если вы хотите, чтобы все было в одном месте и не нужно ничего строить. Однако исходные репозитории на самом деле не являются хорошим местом для этого, хотя сложность там вредит больше, чем в большинстве мест.

— ANone
источник

2

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

Являются ли документы требованием для производства?
У вашей системы развертывания нет необходимых инструментов для создания документации?

Если эти условия выполняются, возможно, вы развертываете с устаревшей системой или системой с особыми ограничениями безопасности. В качестве альтернативы вы можете зафиксировать сгенерированные файлы в ветке релиза и поддерживать чистоту главной ветки.

— Trendfischer
источник

1

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

— Курт Дж. Сэмпсон

2

По-разному. Если эти документы:

Должен быть частью репозитория, как readme.md, то желательно, чтобы они оставались в репозитории git. Потому что это может быть сложно обрабатывать такие ситуации в автоматическом режиме.
Если у вас нет автоматизированного способа их создания и обновления, такого как система CI, и он предназначен для просмотра широкой аудиторией, тогда предпочтительнее хранить их в git-репо.
Занимает много времени, чтобы построить их, а затем оправданно их сохранить.
Предназначены для просмотра широкой аудиторией (например, руководством пользователя), и на их сборку уходит значительное время, в то время как ваши предыдущие документы становятся недоступными (в автономном режиме), а затем их можно хранить в репозитории git.
Предназначены для просмотра широкой аудиторией и должны показывать историю ее изменений / эволюции, может быть проще сохранить прежние версии документа и создать / зафиксировать новую, связанную с предыдущей. Необходимая.
Имеет конкретную общепринятую причину, по которой все команды должны быть приняты, и тогда оправданно держать их в git-репо. (Мы не знаем ваш контекст, вы и ваша команда знаете)

В любом другом сценарии его следует смело игнорировать.

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

— throawableAccount2892391
источник

1

В качестве принципа контроля версий в репозитории должны храниться только «первичные объекты», а не «производные объекты».

Из этого правила есть исключения: а именно, когда есть пользователи репозитория, которым требуются производные объекты, и разумно ожидать, что у них не будет необходимых инструментов для их генерации. Другие соображения весят, как количество материала громоздко? (Будет ли лучше, если бы у всех пользователей были инструменты?)

Экстремальным примером этого является проект, который реализует редкий язык программирования, компилятор которого написан на этом языке (хорошо известные примеры включают Ocaml или Haskell). Если в репозитории находится только исходный код компилятора, никто не сможет его собрать; у них нет скомпилированной версии компилятора, которую они могли бы запустить на виртуальной машине, чтобы они могли скомпилировать исходный код этого компилятора. Более того, последние возможности языка сразу же используются в самом исходном коде компилятора, так что для его сборки всегда требуется близкий к последней версии компилятор: исполняемый файл компилятора месяца, полученный отдельно, не будет компилировать текущий код, потому что код использует языковые функции, которых не было месяц назад. В этой ситуации скомпилированная версия компилятора почти наверняка должна быть проверена в хранилище и обновлена.

— Kaz
источник