Я создатель растущего проекта с открытым исходным кодом. В настоящее время я расстраиваюсь, пытаясь найти лучший способ управления документацией. Вот варианты, которые я рассмотрел:
- HTML-сайт
- Github Wiki
- Файлы разметки, размещенные на Github
- Размещение всех документов в Github README.md
Документация уже написана на Markdown, я просто не могу понять, как я хочу сделать ее доступной. Я действительно заинтересован в Git, так как я могу разветвлять и маркировать документацию так же, как я могу разветвлять и маркировать источник.
Я мог бы использовать библиотеку Markdown для перевода Markdown в HTML и отображения его на стилизованном веб-сайте. Мне нужно было бы загружать изменения на веб-сайт в любое время, когда они были изменены, и было бы трудно управлять всеми различными «тегами» документации.
Github Wikis (насколько я знаю) не меняются в зависимости от вашей ветки. Таким образом, я мог иметь только «основную» версию документации в форме Github Wiki в любой момент времени.
Поместить все это в Github README довольно аккуратно. Я получаю ветвления и пометки, но это немного утомляет в использовании и не поддается легкой навигации.
Я пропускаю какое-то удивительное решение? Какие еще варианты у меня есть?
источник
Ответы:
Я бы сказал, что документация ДОЛЖНА быть в файлах исходного кода (используя любую разметку, которую вы хотите), а затем автоматически генерировать документы из них.
По крайней мере, на вашем сайте вы можете генерировать отформатированные загрузки документов как часть исходного пакета, так что пользователю не нужен специальный инструмент для документирования.
Вероятность того, что кто-то еще исправит / добавит функцию, а затем отредактирует / добавит немного разметочной документации, непосредственно примыкающей к одному и тому же файлу, может быть низкой, НО вероятность того, что они найдут совершенно другой файл в другом хранилище документов, будет немного меньше нуля.
Вы всегда можете иметь tutorial.h, который содержит большие блоки текста, если хотите, но рассматривайте его как часть исходного кода.
источник
Если ваш проект является библиотекой, ничто не сравнится с документацией в стиле javadoc для документирования синтаксиса API из комментариев внутри самого кода.
Что касается документации по учебным пособиям, примерам использования и т. Д. Я настоятельно рекомендую использовать вики-формат. У других проектов, которые я видел, есть отдельные страницы для разных веток. Когда вы запускаете новую ветку, вы просто копируете вещи, которые не изменились, на новую страницу и обновляете ее оттуда.
Моя причина рекомендовать вики анекдотична, но из личного опыта. Я несколько раз вносил обновления документации в проекты с открытым исходным кодом, но все они были в вики. Если я пытаюсь что-то выяснить, а документация вводит в заблуждение или бесполезна, после того, как я это выясню, я обновлю вики, пока я нахожусь в документации, и это свежо в моей памяти. Если не из чувства отдачи, по крайней мере, потому что я знаю, что мне, вероятно, нужно будет снова посмотреть это через год или два.
Если вики не существует, барьер для входа слишком велик, чтобы беспокоиться между выяснением того, как генерируется документация, где она хранится, получением последней информации из системы контроля версий, как вносить изменения, вносить реальные изменения и навигация по спискам рассылки, чтобы получить исправление.
Если вам нужен жесткий контроль над вашей документацией, во что бы то ни стало используйте все, что вам удобнее, потому что вы будете в основном обновлять ее. Если вы хотите поощрять участие сообщества, используйте вики.
источник
Файлы разметки, размещенные с источником, работают очень хорошо.
В РСТ на основе Docutils инструментов, например, могут создать HTML или латексный (и PDF - файлы) из одного набора документов.
Это - в действительности - объединяет ваш вариант 1 и вариант 3.
источник
Если вы не против конвертировать документы из Markdown в reStructuredText, рассмотрите Sphinx . Это так же просто, как уценка, но это намного мощнее.
источник