3

Привет всем!

Написал небольшую библиотеку на PHP. Теперь встал вопрос о создании сайта для нее. Сайт я решил делать с использованием Yii Framework. Ну и само собой разумеется, что на сайте должна быть документация по работе с этой библиотекой: использование, написание плагинов и прочее.

Вот хотел узнать, есть ли какие-нибудь готовые удобные системы по ведению документации. Основные требования - это:

  • хранение всей документации в базе данных, а не в статичных HTML-файлах;
  • наличие веток или версионности. Например, есть документация для версии библиотеки 1.0. Но в версии 1.1 добавились некоторые возможности, которых нет в 1.0. Мне бы хотелось не делать копию всей документации, а выбирать статьи, которые относятся только к определенным версиям;
  • мультиязычность. Причем желательно, чтобы каждая отдельная статья, а не вся документация, имела разные переводы. Чтобы в случае отсутствия перевода, показывать оригинал статьи;
  • подсветка или простое выделение кода.

Заранее спасибо.

P.S. В общем-то, все мои требования отражены на самом сайте Yii: Только, как я понимаю, отдельных модулей и их исходников для создания такой документации самому нигде нет.

UPD:

Я думал, что таких систем видимо-невидимо в инете должно быть. А начал искать - не нашел. Может, у них какое-то название есть специальное и я не так ищу?

4
  • 1
    Почему не github / bitbucket? Код комментировать в стандарте phpDoc, использование/примеры писать в MarkDown (да, в каждой ветке будет своя версия README.md), и в обоих хранилищах можно легко вести баг трекер и вики и принимать коммиты сторонних разработчиков. А может и благодарить их с помощью tip4commit : )
    – Sergiks
    29 сен 2014 в 6:51
  • Вот MarkDown мне кажется удобным для нескольких примеров. А когда примеров уже становится больше десятка, то ориентироваться по ним уже становится сложнее. Нужна какая-та навигация. Ну и на будущее многоязычность не помешает.
    – Dobby007
    29 сен 2014 в 7:58
  • Может быть, конечно, для моей библиотеки это излишне. Но даже если это так, то иметь под рукой такие инструменты и знать как ими пользоваться, никогда не плохо.
    – Dobby007
    29 сен 2014 в 7:58
  • 1
    Вики, в-принципе, как вариант. Но хотелось бы, чтобы она была прям на моем сайте, а не на гитхабе.
    – Dobby007
    29 сен 2014 в 8:02

2 ответа 2

2

Better late than never

http://readthedocs.org/

  • + Версионность
  • + Многоязычность
  • + Автобилд
  • - Все располагается на чужих серверах, можно забрать себе проект с github, но там вряд ли будет подробнейшая документация по поддержке своего сервера
  • + Можно тарнслировать на своем сайте с помощью простого DNS
  • + Подсветка кода
  • + Поиск
1

https://ru.wikipedia.org/wiki/PhpDocumentor - это отличный инструмент.

Он позволит Вам и документацию вести, и подсказки для IDE будут генерироваться, и поддержка версий есть.

5
  • Если я ошибаюсь, то поправьте меня, но я так понял, что он просто нагенерит мне кучу HTML-файлов. Для исходного кода это еще куда ни шло. А вот для обычных страниц с инструкциями: как писать плагины, как пользоваться библиотекой - уже не очень. Опять же, мне еще нужна многоязычность инструкций. Т.е. я вижу только один выход - хранение все в базе данных.
    – Dobby007
    29 сен 2014 в 7:52
  • Нет, Вы не ошибаетесь. С разными версиями языка тут не особо. Тем не менее тег @example есть - чтоб писать примеры использования. Скорее всего, Вам действительно необходимо более редактируемое решение. P.S. В качестве совета: если Вы хотите большей популярности для своей библиотеки, задокументируйте ее PhpDoc, комьюнити это понравиться - подсказки в IDE никому не вредили.
    – Hawk
    29 сен 2014 в 8:05
  • Спасибо. PhpDoc я использую. Без этой штуки тяжело вообще что-то делать даже в IDE. Конечно, не везде у меня комментарии проставлены. Муторно их делать для всех методов и свойств :) ____ @Hawk, перечитал Ваш комментарий еще раз. А что Вы имеете в виду под разными версиями языка?
    – Dobby007
    29 сен 2014 в 8:12
  • Имел ввиду документацию на разных языках (русский, английский,...) сорри что не понятно выразился.
    – Hawk
    29 сен 2014 в 8:16
  • @Hawk, все понятно :) Неужели самому придется писать то, что я хочу...
    – Dobby007
    29 сен 2014 в 9:08

Ваш ответ

By clicking “Отправить ответ”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Всё ещё ищете ответ? Посмотрите другие вопросы с метками или задайте свой вопрос.