Инструмент для написания и сопровождения актуальной документации Open Source проекта?
Занимаюсь разработкой CMS, хотелось бы сделать документацию к нему, чтобы сторонние разработчики могли посмотреть, и понять что к чему.
В принципе, кругом есть PHPDoc секции, можно генерировать документацию на лету, но она какая-то унылая получается, примеры использования в описание методов и классов совать не хотелось бы.
Неплохо было бы сделать что-то в виде простых уроком для начального старта, но полную документацию нужно бы тоже иметь. Думал вести wiki на GutHub, но получается неудобно, актуализировать всё вручную тоже слишком сложно.
Возможно скринкасты?
Какими инструментами пользуетесь вы, как максимально снизить порог вхождения в проект для новых людей?
Я в своё время обратил внимание на lp4all: пишем wiki–страницы в отдельных файлах, пишем wiki–вставки в исходных файлах. И из того, и из другого делаются html страницы, исходные файлы раскрашиваются, wiki–вставки в них форматируются, документацию и исходники можно перекрёстно сослать друг на друга. Ведь иногда проще посмотреть, как это реально сделано, особенно, если документация не часто актуализируется
cyberorg грустненько, если код такой, что приходится писать по нему описание. я стараюсь писать а) комменты б) писать так, чтобы сразу было понятно. Иначе через пару месяцев когда надо разобраться в старом проекте чёрт может голову сломать, что там и как. Плюс диаграммы зависимостей помогают
Значит, что Вы хороший разработчик. Я лично тоже максимально хорошо комментирую код, чтобы потом с легкостью генерились JavaDoc'и.
Но в нашем мире не все умеют писать хороший код.
В некоторых IDE есть возможность писать XML комментарии в отдельный файл, выдранные прямо из исходников. Я этот функционал в MS VS12 оценил — возле собранного проекта ложится xml файлик.
nazarpc, я впервые про Вашу IDE слышу, так что не в курсе — поищите сами.
На крайний случай, такое можно самому написать скриптами, чтобы выдирали комменты в специфичной формулировке из исходников и их отдельно складывали в файлике.
Для этого есть PhpDocumentor, но он дает на выходе только документацию по коду, которой пользоваться не очень удобно, да и не достаточно её. Хочется что-то более комплексное, чтобы и документация по коду, и примеры, и чтобы поддерживать это всё было удобно.
