RDSDataSource: Автогенерация документации для SDK
0 likes360 views
Документ описывает процесс создания API документации, включая выбор систем, таких как HeaderDoc, AppleDoc и Jazzy, а также их особенности и поддерживаемые языки. Также рассматривается процесс разработки гайдов и интеграция с Confluence, в том числе этапы создания и выпуска документации. В заключение обсуждаются планы по развитию и улучшению существующей документации.
RDSDataSource: Автогенерация документации для SDK
- 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 версии на конкретный релиз
- 27. Конец