From 613623fa5349fa53aaf437585031f79f2bdc2749 Mon Sep 17 00:00:00 2001 From: Koitharu Date: Tue, 24 Sep 2024 08:43:47 +0300 Subject: [PATCH] Update information pages --- CONTRIBUTING.md | 75 +++++++++++++++++++++++++------------------------ README.md | 4 +-- 2 files changed, 40 insertions(+), 39 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9c481e8a..a4b87342 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,10 +1,10 @@ # Contributing -The following is guide for creating a Kotatsu parsers. Thanks for taking the time to contribute! +The following is a guide for creating Kotatsu parsers. Thanks for taking the time to contribute! ## Prerequisites -Before you start, please note that the ability to use following technologies is **required**. +Before you start, please note that the ability to use the following technologies is **required**. - Basic [Android development](https://developer.android.com/) - [Kotlin](https://kotlinlang.org/) @@ -16,24 +16,24 @@ Before you start, please note that the ability to use following technologies is - [IntelliJ IDEA](https://www.jetbrains.com/idea/) (Community edition is enough) - Android device (or emulator) -Kotatsu parsers is not a part of Android application, but you can easily develop and test it directly inside an Android -application project and relocate it to the library project when done. +Kotatsu parsers are not a part of the Android application, but you can easily develop and test it directly inside an +Android application project and relocate it to the library project when done. ### Before you start -First, take a look at `kotatsu-parsers` project structure. Each parser is a single class that -extends `MangaParser` class and have a `MangaSourceParser` annotation. -Also pay attention on extensions in `util` package. For example, extensions from `Jsoup` file +First, take a look at the `kotatsu-parsers` project structure. Each parser is a single class that +extends the `MangaParser` class and has a `MangaSourceParser` annotation. +Also, pay attention to extensions in the `util` package. For example, extensions from the `Jsoup` file should be used instead of existing JSoup functions because they have better nullability support and improved error messages. ## Writing your parser So, you want to create a parser, that will provide access to manga from a website. -First, you should explore a website for API availability. +First, you should explore a website to learn about API availability. If it does not contain any documentation about API, [explore network requests](https://firefox-source-docs.mozilla.org/devtools-user/): -some websites use ajax. +some websites use AJAX. - [Example](https://github.com/KotatsuApp/kotatsu-parsers/blob/master/src/main/kotlin/org/koitharu/kotatsu/parsers/site/ru/DesuMeParser.kt) of Json API usage. @@ -42,45 +42,46 @@ some websites use ajax. - [Example](https://github.com/KotatsuApp/kotatsu-parsers/blob/master/src/main/kotlin/org/koitharu/kotatsu/parsers/site/en/MangaTownParser.kt) of pure HTML parsing. -If website is based on some engine it is rationally to use common base class for this one (for example, Madara wordress -theme -and the `MadaraParser` class) +If the website is based on some engine it is rationally to use a common base class for this one (for example, Madara +Wordpress theme and the `MadaraParser` class) ### Parser class skeleton -Parser class must have exactly one primary constructor parameter of type `MangaLoaderContext` and have an -`MangaSourceParser` annotation that provides internal name, title and language of a manga source. - -All functions in `MangaParser` class are documented. Pay attention to some peculiarities: - -- Never hardcode domain. Specify default domain in `configKeyDomain` field and obtain an actual one using `getDomain()`. -- All ids must be unique and domain-independent. Use `generateUid` functions with relative url or some internal id which - is unique across the manga source. -- `sortOrders` set should not be empty. If your source is not support sorting, specify one most relevance value. -- If you cannot obtain direct links to pages images inside `getPages` method, it is ok to use an intermediate url - as `Page.url` and fetch a direct link at `getPageUrl` function. -- You can use _asserts_ to check some optional fields. For example. `Manga.author` field is not required, but if your - source provide such information, add `assert(it != null)`. This will not have any effect on production but help to - find issues during unit testing. -- If your source website (or it's api) uses pages for pagination instead of offset you should extend `PagedMangaParser` +The parser class must have exactly one primary constructor parameter of type `MangaLoaderContext` and have an +`MangaSourceParser` annotation that provides the internal name, title, and language of a manga source. + +All members of the `MangaParser` class are documented. Pay attention to some peculiarities: + +- Never hardcode domain. Specify the default domain in the `configKeyDomain` field and obtain an actual one using + `domain`. +- All IDs must be unique and domain-independent. Use `generateUid` functions with a relative URL or some internal id + that is unique across the manga source. +- The `availableSortOrders` set should not be empty. If your source does not support sorting, specify one most relevant + value. +- If you cannot obtain direct links to page images inside the `getPages` method, it is ok to use an intermediate URL + as `Page.url` and fetch a direct link in the `getPageUrl` function. +- You can use _asserts_ to check some optional fields. For example, the `Manga.author` field is not required, but if + your source provides this information, add `assert(it != null)`. This will not have any effect on production but help + to find issues during unit testing. +- If your source website (or its API) uses pages for pagination instead of offset you should extend `PagedMangaParser` instead of `MangaParser`. -- If your source website (or it's api) do not provide pagination (has only one page of content) you should extend - `SinglePageMangaParser` instead of `MangaParser` nor `PagedMangaParser. -- Your parser may also implement the `Interceptor` interface for additional manipulation of all network requests and/or +- If your source website (or its API) does not provide pagination (has only one page of content) you should extend + `SinglePageMangaParser` instead of `MangaParser` or `PagedMangaParser`. +- Your parser may also implement the `Interceptor` interface for additional manipulation of all network requests and responses, including image loading. ## Development process -During the development it is recommended (but not necessary) to write it directly -in the Kotatsu android application project. You can use `core.parser.DummyParser` class as a sandbox. `Dummy` manga -source is available in debug Kotatsu build. +During the development, it is recommended (but not necessary) to write it directly +in the Kotatsu Android application project. You can use the `core.parser.DummyParser` class as a sandbox. The `Dummy` +manga source is available in the debug Kotatsu build. -Once parser is ready you can relocate your code into `kotatsu-parsers` library project in a `site` package and create a -Pull Request. +Once the parser is ready you can relocate your code into the `kotatsu-parsers` library project in a `site` package and +create a Pull Request. ### Testing -It is recommended to run unit tests before submitting a PR. +It is recommended that unit tests be run before submitting a PR. - Temporary modify the `MangaSources` annotation class: specify your parser(s) name(s) and change mode to `EnumSource.Mode.INCLUDE` @@ -89,5 +90,5 @@ It is recommended to run unit tests before submitting a PR. ## Help -If you need a help or have some questions, ask a community in our [Telegram chat](https://t.me/kotatsuapp) +If you need help or have some questions, ask a community in our [Telegram chat](https://t.me/kotatsuapp) or [Discord server](https://discord.gg/NNJ5RgVBC5). diff --git a/README.md b/README.md index d08264af..b52db6c7 100644 --- a/README.md +++ b/README.md @@ -47,7 +47,7 @@ JVM and Android applications. 3. Usage in code ```kotlin - val parser = mangaLoaderContext.newParserInstance(MangaParserSourceMANGADEX) + val parser = mangaLoaderContext.newParserInstance(MangaParserSource.MANGADEX) ``` `mangaLoaderContext` is an implementation of the `MangaLoaderContext` class. @@ -56,7 +56,7 @@ JVM and Android applications. and [Non-Android](https://github.com/KotatsuApp/kotatsu-dl/blob/master/src/jvmMain/kotlin/org/koitharu/kotatsu_dl/logic/MangaLoaderContextImpl.kt) implementation. - Note that the `MangaParserSourceLOCAL` and `MangaParserSourceDUMMY` parsers cannot be instantiated. + Note that the `MangaParserSource.DUMMY` parsers cannot be instantiated. ## Projects that use the library