Переработана документация Celesta 7.x
Ivan Ponomarev
Всем привет!
Существенно обновлена документация по Celesta 7x. User guide
доступен здесь,
API (JavaDoc) — здесь. Мы ушли с Wiki и
полностью перешли на использование Documentation as Code.
Т. к. суть самого проекта Celesta 7.x изменилась (теперь это библиотека для Java-разработки), в документации переделано довольно многое.
- Прежде всего, появилась JavaDoc-документация как
таковая. Если раньше считалось, что для Jython-разработчика не
требуется знание Java API, то для Java библиотеки невозможно не
иметь опубликованного JavaDoc. В User Guide добавлено много
ссылок на Javadoc. К сожалению, пока что JavaDoc, во-первых,
существенно неполон, а во вторых, имеет место смесь английского
и русского языков. Мы будем постепенно восполнять пробелы и
переводить JavaDoc на английский язык.
- Во-вторых, User Guide переведён на AsciiDoctor и существенно реструктурирован. Всё начинается с раздела "quick start", в котором рассмотрен короткий демо-пример на базе Celesta и Spring Boot. Этот пример можно скачать с гитхаба, собрать и запустить, не устанавливая у себя никаких дополнительных компонент.
- В целом всё переделано под реалии Spring Boot
(конфигурирование, слоистая архитектура проекта и т. п.)
- Вычищены упоминания всех неактуальных для Celesta 7x
возможностей (всё, что связано с сессиями, IDENTITY и т. п.)
- Все примеры кода на Python заменены (и в процессе протестированы!) примерами кода на Java. Код Python буквально разбросан по всей документации и некоторые его артефакты, вероятно, ещё остались. Достаточно сказать, что под конец я по всему тексту в десятке мест заменил слово "None" на "null", а какой ещё поиск-замену надо сделать, неизвестно :-)
Я всё ещё не доволен результатом. Я планирую переписать начальные
разделы: "словарь основных терминов", который был важен на заре
возникновения Celesta, теперь не так важен, как был бы важен
последовательный рассказ о том, как начать работать. По всему
тексту разбросаны сделанные вразнобой диаграммы, которые хорошо бы
полностью заменить на PlantUML (может быть, Коля нам
окажет помощь по этому поводу).
Но в целом документацию на Celesta 7.x сейчас можно считать адекватной. С тем, что теперь есть, можно использовать продукт и развивать его.
С уважением,
ИП