Documenting the mobile toolkits

[mickael-menu]

The mobile toolkits are currently lacking documentation. Let's use this issue to track the work to be done.

Some of the pages will be in the shared mobile repo while platform-dependent ones will be in swift-toolkit or kotlin-toolkit.

The integration guides will be in each platform repo and will be the gateway to more abstract concepts/APIs.

• Integration guides
  • [ ] What to do if you're stuck?
    • Look in the github issues/discussions, then Slack.
    • What kind of issues we can offer support for.
  • [ ] What publication formats are supported by Readium?
  • [x] How to open a publication and read its metadata?
  • [x] How to render a publication on the screen?
  • [x] How to save and restore the last read position?
  • [ ] How to save bookmarks?
  • [ ] How to display page numbers?
    • Explains the difference between page numbers, screen pages and positions
  • [ ] How to show a progress bar for the whole publication?
  • [ ] How to add new text selection menu items?
  • [ ] How to get the current progression / page number in the publication?
  • [x] EPUB: How to add custom fonts?
  • [x] EPUB: How to customize the text and background colors?
  • [ ] How to search through the content of a publication?
  • [x] How to highlight a text selection?
  • [ ] How to display the table of contents?
  • [ ] How to browse an OPDS catalog?
  • [x] How to open publications protected by Readium LCP?
• General concepts
  • [x] Readium architecture (overview of each modules) in the context of Readium mobile
  • [ ] Core models / terms
    • [x] Publication models and extensions
    • [ ] Publication services
      • [ ] Position
      • [ ] Cover
      • [ ] Search
      • [ ] Locator
    • [x] Locator
    • [ ] Fetcher
    • [x] MediaType
  • [ ] Streamer
    • [ ] PublicationParser
    • [ ] HTTP server
  • [ ] Navigator
    • [x] Navigation
    • [x] Decorator
    • [ ] Presentation
    • [ ] Injectable
  • [x] Content Protection
  • [x] Readium CSS
• Contribution guides
  • [ ] How to setup a dev environment
  • [ ] Guidelines to contribute
  • [ ] Licensing?
  • [ ] Detailed overview of each module's architecture
  • [x] How to build the EPUB JavaScript bundles?

[llemeurfr]

Bravo for the initiative Mickaël.

I agree that "How to setup a dev environment" is part of the Contribution Guides, more than Integration Guides: every contributor should make a clean fork and propose PRs for what the can propose to the community.

[ettore]

liking this as well, thanks. I think it would be useful to have a description of the concept of "positions" vs "page numbers", since it's easy to confuse the two things if you're new to Readium. I think this can be approached from both developer and a user/product point of views.

[mickael-menu]

@ettore Yes definitely, I added this as a comment to "How to display page numbers?"