Переработана документация Celesta 7.x

6 views
Skip to first unread message

Ivan Ponomarev

unread,
Nov 29, 2018, 10:34:21 AM11/29/18
to curs-group

Всем привет!

Существенно обновлена документация по 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 сейчас можно считать адекватной. С тем, что теперь есть, можно использовать продукт и развивать его.

С уважением,

ИП


Reply all
Reply to author
Forward
0 new messages