Автогенерация документации для sdk
TRANSCRIPT
![Page 1: Автогенерация документации для SDK](https://reader031.vdocuments.net/reader031/viewer/2022021815/58847e481a28ab5e248b7a9d/html5/thumbnails/1.jpg)
Документация кода
![Page 2: Автогенерация документации для SDK](https://reader031.vdocuments.net/reader031/viewer/2022021815/58847e481a28ab5e248b7a9d/html5/thumbnails/2.jpg)
План• Источники API документации
• Обзор систем для создания API документации
• Выберем систему
• Процесс создания документации
• Процесс создания гайдов
![Page 3: Автогенерация документации для SDK](https://reader031.vdocuments.net/reader031/viewer/2022021815/58847e481a28ab5e248b7a9d/html5/thumbnails/3.jpg)
Источники API документации
• Исходный код, публичный интерфейс
• Quick Help
• Xcode Documentation
• Внешние источники
![Page 4: Автогенерация документации для SDK](https://reader031.vdocuments.net/reader031/viewer/2022021815/58847e481a28ab5e248b7a9d/html5/thumbnails/4.jpg)
Внешние источники• Не нужно скачивать исходный код
• Не нужно искать исходный код на репозитории проекта
• Вся документация в одном месте
• Можно ссылаться на документацию при описании гайдов (html)
![Page 5: Автогенерация документации для SDK](https://reader031.vdocuments.net/reader031/viewer/2022021815/58847e481a28ab5e248b7a9d/html5/thumbnails/5.jpg)
Способы создания API документации
• headerdoc
• appledoc
• jazzy
![Page 6: Автогенерация документации для SDK](https://reader031.vdocuments.net/reader031/viewer/2022021815/58847e481a28ab5e248b7a9d/html5/thumbnails/6.jpg)
Способы создания API документации
Удобство работы
Поддержка objective-c
Поддержка swift
Активно поддержива
ется Красивая
документацияСвои
шаблоны
Документация генерируется сразу для
двух языков
headerdoc - + - - - - -
appledoc + + - - + + -
jazzy ++
(есть проблемы)
+ + + + +
![Page 7: Автогенерация документации для SDK](https://reader031.vdocuments.net/reader031/viewer/2022021815/58847e481a28ab5e248b7a9d/html5/thumbnails/7.jpg)
headerdoc
![Page 8: Автогенерация документации для SDK](https://reader031.vdocuments.net/reader031/viewer/2022021815/58847e481a28ab5e248b7a9d/html5/thumbnails/8.jpg)
headerdoc
![Page 9: Автогенерация документации для SDK](https://reader031.vdocuments.net/reader031/viewer/2022021815/58847e481a28ab5e248b7a9d/html5/thumbnails/9.jpg)
appledoc
![Page 10: Автогенерация документации для SDK](https://reader031.vdocuments.net/reader031/viewer/2022021815/58847e481a28ab5e248b7a9d/html5/thumbnails/10.jpg)
appledoc
![Page 11: Автогенерация документации для SDK](https://reader031.vdocuments.net/reader031/viewer/2022021815/58847e481a28ab5e248b7a9d/html5/thumbnails/11.jpg)
jazzy
![Page 12: Автогенерация документации для SDK](https://reader031.vdocuments.net/reader031/viewer/2022021815/58847e481a28ab5e248b7a9d/html5/thumbnails/12.jpg)
jazzy (+)• Поддержка swift/objective-c
• Документация генерируется для двух языков
• Поддержка dash
• Документация похожа на apple
• Есть ссылки на исходники метода в github/gitlab
• Активно развивается, разрабатывают realm
• Оптимизирован для генерации документации под SDK. Умеет генерировать документацию только для публичных классов
![Page 13: Автогенерация документации для SDK](https://reader031.vdocuments.net/reader031/viewer/2022021815/58847e481a28ab5e248b7a9d/html5/thumbnails/13.jpg)
jazzy (-)
• Для objective-с генерирует документацию по umbrella header
• Не умеет находить файлы objective-c в поддиректориях
• В редких случаях не генерирует доки для swift
![Page 14: Автогенерация документации для SDK](https://reader031.vdocuments.net/reader031/viewer/2022021815/58847e481a28ab5e248b7a9d/html5/thumbnails/14.jpg)
Dash
• Программа для просмотра и навигации по документации
• Библиотека содежит 150+ API
• Поддержка macOS и iOS
![Page 15: Автогенерация документации для SDK](https://reader031.vdocuments.net/reader031/viewer/2022021815/58847e481a28ab5e248b7a9d/html5/thumbnails/15.jpg)
Dash
![Page 16: Автогенерация документации для SDK](https://reader031.vdocuments.net/reader031/viewer/2022021815/58847e481a28ab5e248b7a9d/html5/thumbnails/16.jpg)
Как мы работаем с jazzy?
![Page 17: Автогенерация документации для SDK](https://reader031.vdocuments.net/reader031/viewer/2022021815/58847e481a28ab5e248b7a9d/html5/thumbnails/17.jpg)
fastlane - create_docsEnvironment
• SOURCE_DIR - Папка исходного кода
• SOURCE_URL - Адрес репозитория
• MODULE_NAME - Отображаемое имя SDK
• UMBRELLA_HEADER - Umbrella header SDK
![Page 18: Автогенерация документации для SDK](https://reader031.vdocuments.net/reader031/viewer/2022021815/58847e481a28ab5e248b7a9d/html5/thumbnails/18.jpg)
fastlane - create_docs
Параметры
• branch - Ветка
• version - Отображаемая версия
![Page 19: Автогенерация документации для SDK](https://reader031.vdocuments.net/reader031/viewer/2022021815/58847e481a28ab5e248b7a9d/html5/thumbnails/19.jpg)
fastlanecreate_docs
create_develop_docsНастроен для сборки из
develop рабочей документации.
create_release_docsСобирает документацию для релизной версии. Является
одним из этапа деплоя релиза.
![Page 20: Автогенерация документации для SDK](https://reader031.vdocuments.net/reader031/viewer/2022021815/58847e481a28ab5e248b7a9d/html5/thumbnails/20.jpg)
Создание гайдов
![Page 21: Автогенерация документации для SDK](https://reader031.vdocuments.net/reader031/viewer/2022021815/58847e481a28ab5e248b7a9d/html5/thumbnails/21.jpg)
Confluence + API доки (как нужно)
1. Сделали много фич
2. Создали релиз ветку
3. Исправили баги
4. Написали документацию
5. Релиз
![Page 22: Автогенерация документации для SDK](https://reader031.vdocuments.net/reader031/viewer/2022021815/58847e481a28ab5e248b7a9d/html5/thumbnails/22.jpg)
Confluence + API доки (как получается)
1. Сделали фичу
2. Слили в develop
3. Написали документацию, ссылаясь на develop версию
4. Время релиза
5. Исправили ссылки в confluence на релизную версию
6. Исправили несоответствия документации
7. Релиз
![Page 23: Автогенерация документации для SDK](https://reader031.vdocuments.net/reader031/viewer/2022021815/58847e481a28ab5e248b7a9d/html5/thumbnails/23.jpg)
Confluence
![Page 24: Автогенерация документации для SDK](https://reader031.vdocuments.net/reader031/viewer/2022021815/58847e481a28ab5e248b7a9d/html5/thumbnails/24.jpg)
Confluence
![Page 25: Автогенерация документации для SDK](https://reader031.vdocuments.net/reader031/viewer/2022021815/58847e481a28ab5e248b7a9d/html5/thumbnails/25.jpg)
Какие планы по развитию?
• pull request залить lane на наш репозиторий
• diff версий
• Автоматически заменять ссылки в confluence из develop версии на конкретный релиз
![Page 26: Автогенерация документации для SDK](https://reader031.vdocuments.net/reader031/viewer/2022021815/58847e481a28ab5e248b7a9d/html5/thumbnails/26.jpg)
Где посмотреть
• https://appdistribution.rambler.ru/doc/index.html
![Page 27: Автогенерация документации для SDK](https://reader031.vdocuments.net/reader031/viewer/2022021815/58847e481a28ab5e248b7a9d/html5/thumbnails/27.jpg)
Конец