Skip to content

Commit ff983dc

Browse files
mickael-menuqnga
mickael-menu
and
qnga
authored
Documentation (#486)
Co-authored-by: qnga <32197639+qnga@users.noreply.github.com>
1 parent 374c9c3 commit ff983dc

File tree

14 files changed

+909
-35
lines changed

14 files changed

+909
-35
lines changed

‎CONTRIBUTING.md

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Contributing to the Readium Kotlin Toolkit
2+
3+
First and foremost, thanks for your interest! 🙏 We need contributors like you to help bring this project to fruition.
4+
5+
We welcome many kind of contributions such as improving the documentation, submitting bug reports and feature requests, or writing code.
6+
7+
## Writing code
8+
9+
### Coding standard
10+
11+
We use [`ktlint`](https://github.com/pinterest/ktlint) to ensure code formatting and avoid bikeshedding.
12+
13+
Before submitting a PR, save yourself some trouble by automatically formatting the code with `make format` from the project's root directory.
14+
15+
### Modifying the EPUB Navigator's JavaScript layer
16+
17+
The EPUB navigator injects a set of JavaScript files into a publication's resources, exposing a JavaScript API to the `WebView` under the `readium` global namespace. The JavaScript source code is located under [`readium/navigator/src/main/assets/_scripts`](readium/navigator/src/main/assets/_scripts).
18+
19+
`index-reflowable.js` is the root of the bundle injected in a reflowable EPUB's resources, while `index-fixed.js` is used for a fixed-layout EPUB's resources.
20+
21+
If you make any changes to the JavaScript files, you must regenerate the bundles embedded in the application. First, make sure you have [`corepack` installed](https://pnpm.io/installation#using-corepack). Then, run `make scripts` from the project's root directory.
22+

‎MAINTAINING.md

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# Maintaining the Readium Kotlin toolkit
2+
3+
## Releasing a new version
4+
5+
You are ready to release a new version of the Kotlin toolkit? Great, follow these steps:
6+
7+
1. Figure out the next version using the [semantic versioning scheme](https://semver.org).
8+
2. Test a migration from the last released version.
9+
3. Update the [migration guide](docs/migration-guide.md) in case of breaking changes.
10+
4. Issue the new release.
11+
1. Create a branch with the same name as the future tag, from `develop`.
12+
2. Bump the version numbers in:
13+
* `README`
14+
* `gradle.properties`
15+
* `test-app/build.gradle.kts`
16+
5. Close the version in the `CHANGELOG.md` and `docs/migration-guide.md`, [for example](https://github.com/readium/kotlin-toolkit/commit/011e0d74adc66ec2073f746d815310b838af4fbf).
17+
6. Create a PR to merge in `develop` and verify the CI workflows.
18+
7. Squash and merge the PR.
19+
8. Tag the new version from `develop`.
20+
```shell
21+
git checkout develop
22+
git pull
23+
git tag -a 3.0.1 -m 3.0.1
24+
git push --tags
25+
```
26+
5. Create a new release on GitHub.
27+
* Add an APK to the release page **with LCP enabled**.
28+
6. Publish to Maven Central.
29+
1. Verify that the [`Publish` workflow](https://github.com/readium/kotlin-toolkit/actions/workflows/publish.yml) successfully pushed and closed the release to Maven Central.
30+
2. Sign in to https://s01.oss.sonatype.org/
31+
3. Verify the content of the staging repository.
32+
4. Release the staging repository.
33+
7. Check that the new modules can be imported in an Android project from Maven Central.
34+
8. Merge `develop` into `main`.
35+
36+
### Publishing to Maven Central manually
37+
38+
If the `Publish` workflow fails, you may need to publish to Maven Central manually.
39+
40+
[The Sonatype issue for Readium is located here](https://issues.sonatype.org/browse/OSSRH-85964).
41+
42+
#### With the new vanniktech's Maven publish plugin
43+
44+
1. Make sure you have the secrets in `.envrc` and [direnv](https://direnv.net) installed.
45+
2. Run:
46+
```
47+
./gradlew publishToMavenCentral --no-configuration-cache
48+
```
49+
3. Sign in to https://s01.oss.sonatype.org/
50+
4. Publish manually the previously closed Staging repository
51+
52+
### (Deprecated) With the official Maven publish plugin
53+
54+
1. Make sure you have the secrets in `local.properties`.
55+
2. Run:
56+
```
57+
./gradlew clean assembleRelease
58+
./gradlew androidSourcesJar javadocJar
59+
./gradlew publishReleasePublicationToSonatypeRepository closeSonatypeStagingRepository
60+
```
61+
3. Sign in to https://s01.oss.sonatype.org/
62+
4. Publish manually the previously closed Staging repository
63+
64+
Note that [you can't run the gradlew commands separately](https://github.com/gradle-nexus/publish-plugin#publishing-and-closing-in-different-gradle-invocations), otherwise you get this error:
65+
66+
> No staging repository with name sonatype created
67+
68+
## Troubleshooting
69+
70+
### GitHub CI workflow is stuck
71+
72+
If a CI workflow is stuck with this message:
73+
74+
```
75+
Requested labels: ubuntu-18.04
76+
Job defined at: readium/kotlin-toolkit/.github/workflows/docs.yml@refs/heads/main
77+
Waiting for a runner to pick up this job...
78+
```
79+
80+
Try to update the version of the OS image in the workflow.

‎README.md

Lines changed: 1 addition & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -2,18 +2,7 @@
22

33
[Readium Mobile](https://github.com/readium/mobile) is a toolkit for ebooks, audiobooks and comics written in Swift & Kotlin.
44

5-
This toolkit is a modular project, which follows the [Readium Architecture](https://github.com/readium/architecture). The different modules are found under [`readium/`](readium).
6-
7-
* [`shared`](readium/shared) – Shared `Publication` models and utilities
8-
* [`streamer`](readium/streamer) – Publication parsers and local HTTP server
9-
* [`navigator`](readium/navigator) – Plain `Fragment` and `Activity` classes rendering publications
10-
* [`opds`](readium/opds) – Parsers for OPDS catalog feeds
11-
* [`lcp`](readium/lcp) – Service and models for [Readium LCP](https://www.edrlab.org/readium-lcp/)
12-
* [`adapters`](readium/adapters) – Adapters to use third-party libraries with Readium.
13-
* [`adapters/pdfium`](readium/adapters/pdfium) – Parse and render PDFs using the open source library [PdfiumAndroid](https://github.com/barteksc/PdfiumAndroid).
14-
* [`adapters/pspdfkit`](readium/adapters/pspdfkit) – Parse and render PDFs using the commercial library [PSPDFKit](https://pspdfkit.com/).
15-
16-
A [Test App](test-app) demonstrates how to integrate the Readium Kotlin toolkit in your own reading app.
5+
:point_up: **Take a look at the [guide to get started](docs/guides/getting-started.md).** A [Test App](test-app) demonstrates how to integrate the Readium Kotlin toolkit in your own reading app.
176

187
:question: **Find documentation and API reference at [readium.org/kotlin-toolkit](https://readium.org/kotlin-toolkit)**.
198

‎docs/guides/README.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# User guides
2+
3+
* [Getting started](getting-started.md)
4+
* [Opening a publication](open-publication.md)
5+
* [Extracting the content of a publication](content.md)
6+
* [Supporting PDF documents](pdf.md)
7+
* [Text-to-speech](tts.md)
8+
* [Supporting Readium LCP](lcp.md)
9+
* [Navigator](navigator/navigator.md)
10+
* [Configuring the Navigator](navigator/preferences.md)
11+
* [Font families in the EPUB navigator](navigator/epub-fonts.md)
12+
* [Media Navigator](navigator/media-navigator.md)

‎docs/guides/getting-started.md

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
# Getting started
2+
3+
The Readium Kotlin toolkit enables you to develop reading apps for Android and ChromeOS. It provides built-in support for multiple publication formats such as EPUB, PDF, audiobooks, and comics.
4+
5+
:warning: Readium offers only low-level tools. You are responsible for creating a user interface for reading and managing books, as well as a data layer to store the user's publications. The Test App is an example of such integration.
6+
7+
## Design principles
8+
9+
The toolkit has been designed following these core tenets:
10+
11+
* **Modular**: It is divided into separate modules that can be used independently.
12+
* **Extensible**: Integrators should be able to support a custom DRM, publication format or inject their own stylesheets without modifying the toolkit itself.
13+
* **Opiniated**: We adhere to open standards but sometimes interpret them for practicality.
14+
15+
## Modules
16+
17+
### Main modules
18+
19+
* `readium-shared` contains shared `Publication` models and utilities.
20+
* `readium-streamer` parses publication files (e.g. an EPUB) into a `Publication` object.
21+
* [`readium-navigator` renders the content of a publication](navigator/navigator.md).
22+
* [`readium-navigator-media-audio` renders audiobooks](navigator/media-navigator.md)
23+
* [`readium-navigator-media-tts` renders publication with a text-to-speech engine](tts.md)
24+
25+
### Specialized packages
26+
27+
* `readium-opds` parses [OPDS catalog feeds](https://opds.io) (both OPDS 1 and 2).
28+
* [`readium-lcp` downloads and decrypts LCP-protected publications](lcp.md).
29+
30+
### Adapters to third-party dependencies
31+
32+
* `readium-adapter-exoplayer` provides an [ExoPlayer](https://exoplayer.dev) adapter for the [`AudioNavigator`](navigator/media-navigator.md).
33+
* [`readium-adapter-pdfium`](../../readium/adapters/pdfium/README.md) provides a [Pdfium](https://github.com/barteksc/AndroidPdfViewer) adapter for the [PDF Navigator](pdf.md).
34+
* [`readium-adapter-pspdfkit`](../../readium/adapters/pspdfkit/README.md) provides a [PSPDFKit](https://pspdfkit.com) adapter for the [PDF Navigator](pdf.md).
35+
36+
## Overview of the shared models (`readium-shared`)
37+
38+
The Readium toolkit provides models used as exchange types between packages.
39+
40+
### Publication models
41+
42+
#### Publication
43+
44+
`Publication` and its sub-components represent a single publication – ebook, audiobook or comic. It is loosely based on the [Readium Web Publication Manifest](https://readium.org/webpub-manifest/).
45+
46+
A `Publication` instance:
47+
48+
* holds the metadata of a publication, such as its author or table of contents,
49+
* allows to read the contents of a publication, e.g. XHTML or audio resources,
50+
* provides additional services, for example content extraction or text search.
51+
52+
#### Link
53+
54+
A [`Link` object](https://readium.org/webpub-manifest/#24-the-link-object) holds a pointer (URL) to a resource or service along with additional metadata, such as its media type or title.
55+
56+
The `Publication` contains several `Link` collections, for example:
57+
58+
* `readingOrder` lists the publication resources arranged in the order they should be read.
59+
* `resources` contains secondary resources necessary for rendering the `readingOrder`, such as an image or a font file.
60+
* `tableOfContents` represents the table of contents as a tree of `Link` objects.
61+
* `links` exposes additional resources, such as a canonical link to the manifest or a search web service.
62+
63+
#### Locator
64+
65+
A [`Locator` object](https://readium.org/architecture/models/locators/) represents a precise location in a publication resource in a format that can be stored and shared across reading systems. It is more accurate than a `Link` and contains additional information about the location, e.g. progression percentage, position or textual context.
66+
67+
`Locator` objects are used for various features, including:
68+
69+
* reporting the current progression in the publication
70+
* saving bookmarks, highlights and annotations
71+
* navigating search results
72+
73+
### Data models
74+
75+
#### Asset
76+
77+
An `Asset` represents a single file or package and provides access to its content. There are two types of `Asset`:
78+
79+
* `ContainerAsset` for packages which contains several resources, such as a ZIP archive.
80+
* `ResourceAsset` for accessing a single resource, such as a JSON or PDF file.
81+
82+
`Asset` instances are obtained through an `AssetRetriever`.
83+
84+
You can use the `asset.format` to identify the media type and capabilities of the asset.
85+
86+
```kotlin
87+
if (asset.format.conformsTo(Specification.Lcp)) {
88+
// The asset is protected with LCP.
89+
}
90+
if (asset.format.conformsTo(Specification.Epub)) {
91+
// The asset represent an EPUB publication.
92+
}
93+
```
94+
95+
#### Resource
96+
97+
A `Resource` provides read access to a single resource, such as a file or an entry in an archive.
98+
99+
`Resource` instances are usually created by a `ResourceFactory`. The toolkit ships with various implementations supporting different data access protocols such as local files, HTTP, Android Content Providers, etc.
100+
101+
#### Container
102+
103+
A `Container<Resource>` provides read access to a collection of resources. `Container` instances representing an archive are usually created by an `ArchiveOpener`. The toolkit ships with a `ZipArchiveOpener` supporting local and remote ZIP files.
104+
105+
`Publication` objects internally use a `Container<Resource>` to expose its content.
106+
107+
## Opening a publication (`readium-streamer`)
108+
109+
To retrieve a `Publication` object from a publication file like an EPUB or audiobook, you can use an `AssetRetriever` and `PublicationOpener`.
110+
111+
```kotlin
112+
// Instantiate the required components.
113+
val httpClient = DefaultHttpClient()
114+
val assetRetriever = AssetRetriever(
115+
contentResolver = context.contentResolver,
116+
httpClient = httpClient
117+
)
118+
val publicationOpener = PublicationOpener(
119+
publicationParser = DefaultPublicationParser(
120+
context,
121+
httpClient = httpClient,
122+
assetRetriever = assetRetriever,
123+
pdfFactory = PdfiumDocumentFactory(context)
124+
)
125+
)
126+
127+
// Retrieve an `Asset` to access the file content.
128+
val url = File("/path/to/book.epub").toUrl()
129+
val asset = assetRetriever.retrieve(url)
130+
.getOrElse { /* Failed to retrieve the Asset */ }
131+
132+
// Open a `Publication` from the `Asset`.
133+
val publication = publicationOpener.open(asset, allowUserInteraction = true)
134+
.getOrElse { /* Failed to access or parse the publication */ }
135+
136+
print("Opened ${publication.metadata.title}")
137+
```
138+
139+
The `allowUserInteraction` parameter is useful when supporting a DRM like Readium LCP. It indicates if the toolkit can prompt the user for credentials when the publication is protected.
140+
141+
[See the dedicated user guide for more information](open-publication.md).
142+
143+
## Accessing the metadata of a publication
144+
145+
After opening a publication, you may want to read its metadata to insert a new entity into your bookshelf database, for instance. The `publication.metadata` object contains everything you need, including `title`, `authors` and the `published` date.
146+
147+
You can retrieve the publication cover using `publication.cover()`.
148+
149+
## Rendering the publication on the screen (`readium-navigator`)
150+
151+
You can use a Readium navigator to present the publication to the user. The `Navigator` renders resources on the screen and offers APIs and user interactions for navigating the contents.
152+
153+
Please refer to the [Navigator guide](navigator/navigator.md) for more information.

‎docs/guides/index.md

Lines changed: 0 additions & 9 deletions
This file was deleted.

0 commit comments

Comments
 (0)