Помимо различных приложений в нашей команде разрабатывается несколько SDK, и вопрос с генерацией документации становится всё более актуальным. Михаил рассказал какие системы для создание документации существуют, чем они хороши и какую из них мы выбрали для своих нужд. Кроме этого освещаются вопросы исползования такой документации и ее автоматического деплоя через Jenkins и fastlane.
RDSDataSource - внутренние пятничные митапы iOS-команды RAMBLER&Co.
2. План
• Источники API документации
• Обзор систем для создания API документации
• Выберем систему
• Процесс создания документации
• Процесс создания гайдов
4. Внешние источники
• Не нужно скачивать исходный код
• Не нужно искать исходный код на репозитории
проекта
• Вся документация в одном месте
• Можно ссылаться на документацию при описании
гайдов (html)
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
21. Confluence + API доки (как нужно)
1. Сделали много фич
2. Создали релиз ветку
3. Исправили баги
4. Написали документацию
5. Релиз
22. Confluence + API доки
(как получается)
1. Сделали фичу
2. Слили в develop
3. Написали документацию, ссылаясь на develop версию
4. Время релиза
5. Исправили ссылки в confluence на релизную версию
6. Исправили несоответствия документации
7. Релиз
25. Какие планы по развитию?
• pull request залить lane на наш репозиторий
• diff версий
• Автоматически заменять ссылки в confluence из
develop версии на конкретный релиз