![](https://github.com/CakesTwix.png)
Зробити внесок
Дізнайтеся, як допомогти у перекладі або в розробці додатку та парсерів.
Рекомендації щодо внеску до додатку
- Якщо ви хочете виправити помилку або реалізувати нову функцію, про яку вже згадувалося в GitHub Issues, будь ласка, призначте це питання собі та/або прокоментуйте його.
- Якщо вам потрібно впровадити нову функцію, будь ласка, відкрийте тему або обговорення щодо неї, щоб переконатися, що вона буде прийнята.
- Переклади повинні контролюватися за допомогою платформи Weblate.
- Якщо ви хочете додати нове джерело манґи, зверніться до репозиторію парсерів.
Рефакторинг або деякі покращення інтерфейсу також можуть бути прийняті, однак, будь ласка, дотримуйтесь наступних принципів:
- Швидкість роботи має значення. У випадку вибору між красою вихідного коду та швидкістю роботи, пріоритетом має бути швидкість роботи додатка.
- Будь ласка, не змінюйте README.md та інші *.md (за винятком усунення помилок).
- Уникайте додавання нових залежностей без необхідності. Розмір APK важливий.
Настанови щодо внеску до репозиторію парсерів
Нижче наведено настанови щодо створення парсеру Kotatsu. Дякуємо, що знайшли час для участі!
Передумови для участі
Перед початком зауважте, що вміння користуватися наведеними нижче технологіями є необхідним.
- Базові знання розробки під Android
- Kotlin
- Web scraping (JSoup) або JSON API
Інструменти
- Android Studio
- IntelliJ IDEA (Community edition є достатнім для розробки)
- Android-пристрій (або емулятор)
Парсери Kotatsu не є частиною додатку для Android, але ви можете легко розробити і протестувати його безпосередньо в проекті додатку для Android і перемістити його до проекту бібліотеки, коли це буде готове.
Перш ніж почати
Спочатку подивіться на структуру проекту kotatsu-parsers
. Кожен парсер є окремим класом, який розширює клас MangaParser
і має анотацію MangaSourceParser
. Також зверніть увагу на розширення в пакеті util
. Наприклад, розширення з файлу Jsoup
слід використовувати замість існуючих функцій JSoup, тому що вони мають кращу підтримку nullability значень та покращені повідомлення про помилки.
Написання парсеру
Отже, ви хочете створити парсер, який надаватиме доступ до манґи з веб-сайту. По-перше, вам слід дослідити веб-сайт на предмет наявності API. Якщо він не містить жодної документації про API, то дослідіть мережеві запити: деякі сайти використовують ajax.
Якщо сайт побудований на якомусь движку, раціонально використовувати загальний для нього базовий клас (наприклад, Madara wordpress тема і клас MadaraParser
)
Скелет класу парсеру
Клас Parser повинен мати рівно один первинний параметр конструктора типу MangaLoaderContext
і мати анотацію MangaSourceParser
яка містить внутрішню назву, заголовок та мову джерела манґи.
Всі функції класу MangaParser
задокументовані. Зверніть увагу на деякі особливості:
- Ніколи не задавайте домен hardcod'ом. Вкажіть домен за замовчуванням у полі
configKeyDomain
і отримайте актуальний домен за допомогоюgetDomain()
. - Всі ідентифікатори повинні бути унікальними і не залежати від домену. Використовуйте функцію
generateUid
з відносним посиланням або внутрішнім ідентифікатором, який є унікальним у всьому джерелі манґи. - Параметр `sortOrders не повинен бути порожнім. Якщо ваше джерело не підтримує сортування, вкажіть одне найбільш релевантне значення.
- Якщо ви не можете отримати прямі посилання на зображення сторінок у методі
getPages
, ви можете використати проміжний адрес якPage.url
і отримати пряме посилання у функціїgetPageUrl
. - Ви можете використовувати asserts для перевірки деяких необов'язкових полів. Наприклад. Поле
Manga.author
не є обов'язковим, але якщо ваше джерело містить таку інформацію, додайтеassert(it != null)
. Це не вплине на роботу додатку, але допоможе знайти проблеми під час модульного тестування. - Якщо на сайті (або його api) для пагінації використовуються сторінки, а не зміщення, вам слід використовувати
PagedMangaParser
замістьMangaParser
. - Ваш парсер може також реалізувати інтерфейс
Interceptor
для додаткової маніпуляції з усіма мережевими запитами та/або відповідями, включаючи завантаження зображень.
Процес розробки
Під час розробки рекомендується (але не обов'язково) писати його безпосередньо у проекті програми Kotatsu для Android. Ви можете використовувати клас core.parser.DummyParser
як пісочницю. Манґа Dummy
доступний у debug збірці Kotatsu.
Після того, як парсер буде готовий, ви можете перемістити ваш код у проект бібліотеки kotatsu-parsers
у пакеті site
і створити Pull Request.
Тестування
Перед відправкою PR рекомендується провести юніт-тести.
- Тимчасово змініть клас анотації
MangaSources
: вкажіть ім'я вашого(их) парсеру(ів) та змініть режим наEnumSource.Mode.INCLUDE
. - Запустіть `MangaParserTest
gradlew :test --tests "org.koitharu.kotatsu.parsers.MangaParserTest"
gradlew :test --tests "org.koitharu.kotatsu.parsers.MangaParserTest"
- За бажанням ви можете запустити gradle-завдання
generateTestsReport
, щоб отримати досить читабельний html-звіт за результатами тестування.
Допомога
Якщо вам потрібна допомога або у вас є запитання, зверніться до спільноти в нашому Телеграм-чаті або на Discord-сервері.