Stas Karter: Вы лучше спросите, что вам непонятно :)
1. Что это за формат хорошо написано здесь: https://ru.wikipedia.org/wiki/DocBook либо на англоязычной версии.
2. Как делать из этого формата представление (т.е. выходные форматы) написано здесь: wiki.docbook.org
3. Где редактировать - да хоть в Notepad, vim и т.п. Если интересует GUI, то можно попробовать www.xmlmind.com/xmleditor НО! Он стоит денег, поэтому вам, как студенту, можно использовать evaluation только в течении 30 дней. Не думаю, что вы будете его покупать.
maximus: DITA вам не нужна, уж поверьте :)
Если вы определились с форматом (например, Markdown), тогда дальше уже ищите примеры отображения и смотрите, каким образом это устроено у каждой системы.
Почему так? Просто text-based форматы (adoc, md, rst) в это плане более требовательны к изначальной структуре - т.е. вы не сможете потом автоматически их разбивать на куски (про использованием sed/awk я не говорю). С xml-based форматами (Docbook, DITA) в этом смысле проще, т.к. всегда есть xslt, который разобьет вам все, как надо в любой пропорции.
Одна из ошибок начинающих - смотрят на интерфейс. НО! Интерфейс и формат хранения/редактирования - это две совершенно разные вещи. Вам надо сначала определить формат хранения, а потом уже под этот формат хранения искать себе морду для генерации. Только так.
Виталий Столяров: Тогда вам надо:
1. Определить, что конкретно вы будете документировать.
2. Надо ли вам выцеплять это автоматически.
3. Попробовать несколько инструментов в виде теста. Про doxygen вы уже знаете. Можете еще попробовать Sphinx. Или еще погуглить. Для REST - я приводил инструменты ранее.
Виталий Столяров: Вы противоречите сами себе. Приведу цитаты:
- "сопровождение написанного кода документацией, автоматически сгенерированной из комментариев к соответствующему коду"
однако с другой стороны вы отвечаете на вопрос:
- "Надо ли хранить версионность всего этого добра - нет".
Сопровождение НЕ может быть без SCM. Это принципиально.
Давайте я объясню вам, в чем вы неправы. Вы хотите получить "что-то" и "прямо сейчас", "не задумываясь о требованиях". Я же, со своей стороны, даю советы "как надо", а не "как хочется". Безусловно, на тостере много людей, которые практически всегда отвечают не задумывась "Я использую X, попробуй", "Слышал, что Y подходит". Если вас удовлетворят такие ответы без уточняющих вопросов - без проблем - думаю вам здесь подскажут.
Виталий Столяров: Так в том то и дело. По требованиям выбираются инструменты и процессы, а не наоборот. Вы, конечно, можете попробовать от обратного, но это будет, мягко скажем, неоптимально :)
Виталий Столяров: Виталий, по вашему ответу я уверен, вам надо основательно подумать над моими изначальными вопросами, осознать их и ответить на них. Даже, если это займет несколько дней. На текущий момент я вижу - вы смешиваете все в кучу. Т.е. вы просите подсказать вам решение конкретной проблемы, но не можете сформулировать четко эту проблему(-ы) - например, у вам по ходу диалога появляются все новые и новые требования.
Виталий Столяров: Так вы сначала определитесь, нужен только API или нет? :) Т.к. разница очень большая. Если вам нужен только API, то вам будет достаточно:
- генератора комментариев из кода.
- что-то типа Swagger (для REST API). Здесь еще существуют другие нотации и инструментарий - RAML и WADL (последний основан на xml, первые два на json + yaml в качестве "человекочитаемого" варианта).
- web сервер для отображения всего добра.
- скрипты генерации (проще самописные, т.к. вариантивность маленькая).
ОДНАКО, если вам надо делать нормальную документацию: ТЗ, архитектурные документы, руководства администратора, white papers и т.п. (т.е. то, что создается человеком, как документ, содержит иллюстрации и т.п.), то инструментарием выше вам не обойтись.
Вам придется добавлять:
- SCM (обязательно)
- Authoring tools (чтобы писать)
- generation tools + CI (чтобы все генерилось без участия человека).
Если вероятность расширения продукта велика и вынос наружу будет (а это только вам решать), то следующие элементы в структуре must have:
- SCM
- Authoring tools
- CI
Лично я занимаюсь сложными системами, и, конечно, мог бы вам посоветовать использовать много чего, но все-таки вопросы цены внедрения/сопровождения имеет немаловажное значение. Не зря я вам посоветовал посмотреть Где лучше всего вести документацию по сервису? - это напрямую относится к деньгам при выборе решения.
Виталий Столяров: И еще... как я понимаю, нужен только API и все? Т.е. никаких руководств, архитектурных решений и т.п. (т.е. "нормальных документов") не нужно.
Виталий Столяров: п.2 противоречит п. 1, а также пункту "для чего". Печатка нужна только для распространения наружу. Вы не будете печатать у себя + искать внутри. Вам нужен только html c поддержкой поиска.
п.7 - вы уверены в том, что вам не нужно будет держать версионность? Т.е. вопрос коллеги типа "а как там у нас это было реализовано в предыдущей останется без ответа" (точнее, без ответа из документации).
На уровне XSLT вопрос не в количестве добавляемых объектов (хоть 5, хоть 1000), а в сложности логики добавляемых элементов. Написать обычное xslt преобразование, добавляющее внутрь всех элементов А элемент B - дело 5 минут. Другое дело, что кто возьмется за такое.
Вся суть в том, что вам надо совсем отстранить "студентка-техписательницу" от какой-либо структуры и здесь это можно сделать. Т.е. вы даете ей редактор (в моей схеме - Authoring tool) и она там пишет - все. Остальное - цепочки преобразований, топиков и т.п. остается на уровне автоматизации. Здесь только один вопрос - сможет ли она владеть чем-то "не ворд" для набивания текста. По моему опыту - научить реально, хотя и с усилиями.
Вы можете попробовать (просто сделать один шаг) - загрузить www.xmlmind.com/xmleditor evaliation. Посмотреть сюда, как это работает: www.xmlmind.com/xmleditor/tutorial.html Хотя сразу же предупреждаю, что там по умолчанию все основано на gui-действиях и оно дольше, чем сделать keyboard shortcuts.
Вам надо понять только одну вещь - wiki и другие WISYWIG системы хороши для создания контента сотрудниками с нулевым уровнем знаний :) ... но ровно до тех пор, пока контентом не надо управлять. Когда начинается серьезная работа, то без single sourcing уже не обойтись.
Внешняя система по умолчанию ничего не будет переваривать - она покажет 404 и все. По мере нарастания контента это будет большой головной болью (про стартапы я не говорю :) - там мало контента. Кстати, Atlassian со своей Confluence уже сталкивается с такой проблемой именно из-за title в url. Если вы посмотрите (вдумчиво) на их хелпы, то количество 404 уже неприлично большое для 6 версий каждого продукта.
Что касается велосипеда, то лучше не изобретать. По умолчанию, имя файла должно быть != title. Т.е. должен быть какой-нибудь uniq ID, который не изменятся со временем. Что касаемо wiki-base, y Atlassian было это в свое время, но они почему-то отказались, чем сделали большие проблемы для компаний (в джире есть целый тред по этому поводу). Другое дело, что им пофигу на это, т.к. показатали дохода и так позволяют не парится о существующих процентах пользователей :)
Что касаемо тех стандартов, о которых я говорю, то там это по умолчанию из коробки. Т.к. title пишется в head html, а название файла - в uri.
Ваш пример: http://*Ваш_сайт*/xwiki/bin/view/Test+page/%D1%81%... - имеет очень много проблем. При изменении title - любые отправленные ссылки становятся недействительными. С точки хрения принципа переносимости адреса должны быть "content agnostic".
Это сематнические стандарты разметки. При использовании этих стандартов ВЫ настраиваете все так, как хотите. В их основе: XML, а также готовые "из коробки" xsl преобразования. Как вы измените готовый xsl (дополните его своим преобразованием), то и будет. Т.е. это управление контентом в автоматическом режиме с помощью xslt-скриптов - полная автоматизация.
При использовании Docbook/XML вы отделяете содержимое и представление. И сосредотачиваетесь на содержимом - текстах, картинках и т.п.. Это называется технология единого источника в технической документации (single sourcing technical documentation) - содержимое имеет семантическую структуру, не связанную с выходным форматом.
Приведу лишь пример. Очень показательный. Вы, наверное, знаете про ГОСТ (2.x, 19.x, 34.x). Так вот. Многие просто изнывают от требований рамочек, страницек и т.п. Одна из команд сделала xsl преобразование для формирования именно ГОСТовский документов (https://bitbucket.org/Lab50/espd-docbook5/overview). Т.е. их одного источника можете получить ГОСТ, а можете что-то свое (в обычном "вордовском варианте" вы не сможете получить это без полного переформатирования).
Только, если (хотя бы два из):
- несколько проектов;
- несколько клиентов и необходимость компоновки (reuse content);
- несколько форматов вывода;
- необходимо управление контентом.
если цель "только для html" и "написать и забыть" - то использование docbook - микроскопом забивать гвозди :)
1. Что это за формат хорошо написано здесь: https://ru.wikipedia.org/wiki/DocBook либо на англоязычной версии.
2. Как делать из этого формата представление (т.е. выходные форматы) написано здесь: wiki.docbook.org
3. Где редактировать - да хоть в Notepad, vim и т.п. Если интересует GUI, то можно попробовать www.xmlmind.com/xmleditor НО! Он стоит денег, поэтому вам, как студенту, можно использовать evaluation только в течении 30 дней. Не думаю, что вы будете его покупать.