Помимо различных приложений в нашей команде разрабатывается несколько SDK, и вопрос с генерацией документации становится всё более актуальным. Михаил рассказал какие системы для создание документации существуют, чем они хороши и какую из них мы выбрали для своих нужд. Кроме этого освещаются вопросы исползования такой документации и ее автоматического деплоя через Jenkins и fastlane. RDSDataSource - внутренние пятничные митапы iOS-команды RAMBLER&Co.

1. Документация кода

2. План
• Источники API документации
• Обзор систем для создания API документации
• Выберем систему
• Процесс создания документации
• Процесс создания гайдов

3. Источники API
документации
• Исходный код, публичный интерфейс
• Quick Help
• Xcode Documentation
• Внешние источники

4. Внешние источники
• Не нужно скачивать исходный код
• Не нужно искать исходный код на репозитории
проекта
• Вся документация в одном месте
• Можно ссылаться на документацию при описании
гайдов (html)

5. Способы создания API
документации
• headerdoc
• appledoc
• jazzy

6. Способы создания API
документации
Удобство
работы
Поддержка
objective-c
Поддержка
swift
Активно
поддержива
ется
Красивая
документация
Свои
шаблоны
Документация
генерируется
сразу для
двух языков
headerdoc - + - - - - -
appledoc + + - - + + -
jazzy +
+
(есть
проблемы)
+ + + + +

7. headerdoc

8. headerdoc

9. appledoc

10. appledoc

11. jazzy

12. jazzy (+)
• Поддержка swift/objective-c
• Документация генерируется для двух языков
• Поддержка dash
• Документация похожа на apple
• Есть ссылки на исходники метода в github/gitlab
• Активно развивается, разрабатывают realm
• Оптимизирован для генерации документации под SDK. Умеет
генерировать документацию только для публичных классов

13. jazzy (-)
• Для objective-с генерирует документацию по
umbrella header
• Не умеет находить файлы objective-c в
поддиректориях
• В редких случаях не генерирует доки для swift

14. Dash
• Программа для просмотра и навигации по
документации
• Библиотека содежит 150+ API
• Поддержка macOS и iOS

15. Dash

16. Как мы работаем с jazzy?

17. fastlane - create_docs
Environment
• SOURCE_DIR - Папка исходного кода
• SOURCE_URL - Адрес репозитория
• MODULE_NAME - Отображаемое имя SDK
• UMBRELLA_HEADER - Umbrella header SDK

18. fastlane - create_docs
Параметры
• branch - Ветка
• version - Отображаемая версия

19. fastlane
create_docs
create_develop_docs
Настроен для сборки из
develop рабочей
документации.
create_release_docs
Собирает документацию для
релизной версии. Является
одним из этапа деплоя релиза.

20. Создание гайдов

21. Confluence + API доки (как нужно)
1. Сделали много фич
2. Создали релиз ветку
3. Исправили баги
4. Написали документацию
5. Релиз

22. Confluence + API доки
(как получается)
1. Сделали фичу
2. Слили в develop
3. Написали документацию, ссылаясь на develop версию
4. Время релиза
5. Исправили ссылки в confluence на релизную версию
6. Исправили несоответствия документации
7. Релиз

23. Confluence

24. Confluence

25. Какие планы по развитию?
• pull request залить lane на наш репозиторий
• diff версий
• Автоматически заменять ссылки в confluence из
develop версии на конкретный релиз

26. Где посмотреть
• https://appdistribution.rambler.ru/doc/index.html

27. Конец