Godot-docs: Downloaded ePub says "The book is corrupt." when opened in Apple Books app.

[botteu]

Stable version.

When trying to open the ePub-version of the documentation in Apple Books app, I get the message "This book can't be opened. The book is corrupt."
Don't know if this holds true for all ebook-readers though.

https://docs.godotengine.org/en/stable/

[Calinou]

The ePub and PDF generated by Read the Docs tends to not be very pretty anyway.

[botteu]

I see :) But I'd still like to try it. Love what you guys are doing btw ❤️

[hazarek]

Don't know if this holds true for all ebook-readers though.

Epub file for all readers is completely corrupt. I opened the same issue years ago. The epub download link has been there for years. People downloads 128 mb file and waste their time. Everyone should take this as a principle;
DON'T PUBLISH IF IT DOESN'T WORK.

[Calinou]

@hazarek Please calm down. Godot is a community-developed project with no warranties made (as per its license).

ePub builds have been re-enabled recently (see https://github.com/godotengine/godot-docs/issues/3789). Maybe we'll have to disable them again. That said, I'm not sure if we can remove old ePub downloads from Read the Docs entirely.

[hazarek]

@hazarek Please calm down. Godot is a community-developed project with no warranties made (as per its license).

ePub builds have been re-enabled recently (see #3789). Maybe we'll have to disable them again. That said, I'm not sure if we can remove old ePub downloads from Read the Docs entirely.

I said ethically, it's not about giving guarantees. it's about being sensitive to other people living in the world.

[Bruce200]

My solution is to make it a Kindle e-book, which can be read on various mobile devices as well as some PCs, and there is always the web version of Kindle reading. Check that out here.

[akien-mga]

The ePub works for me with the Okular reader on Linux:

It takes a couple minutes to load due to the sheer size of the file and amount of content to format.

IMO those gigantic ePub or (currently disabled, as it fails building) PDF downloads are useless, but users keep asking for them. Once uploaded by ReadTheDocs, we can't remove them ourselves without asking ReadTheDocs admins to intervene.

The only properly usable static download option would be a ZIP with all HTML pages (i.e. the exact same content as the online version), but ReadTheDocs currently only offers a "SingleHTML" download option (all content in a single page, so again 100+ MB and unusable): https://github.com/readthedocs/readthedocs.org/issues/4190

[akien-mga]

I disabled ePub generation again with e95cb6978c96fcf6bbe7d0abd29b334991c46e8e.

I'll ask RTD admins to wipe all current downloads.

[Bruce200]

I wonder if there would be some way to convert the "Single HTML" file into something else, either using some online tool, or maybe by writing our own.
All the text is there for a book format, so it would just be a matter of taking an html tag and turning it into the proper format (e.g. turning "p" tags to small text, "h1" tags to headers) and then encoding it.
My previous comment was potentially turning the docs into a Kindle e-book. We could either write it to a MOBI format directly, or copy-and-paste the text generated with whatever formatting tags it needs to be put into Amazon's Kindle book generator.
I'll check to see what making a kindle e-book entails, but I'm on vacation right now so I couldn't do anything immediately.

[Bruce200]

Did some research, and it looks like there are a number of changes to certain tags that need to be made (probably using a simple program that generates copy and paste), but it does look like you can turn HTML into a Kindle book. Table of contents seem like they may need their own HTML pages, though. Will look into this more later.

[akien-mga]

@Bruce200 We don't have control over the "Downloads" section of ReadTheDocs, beyond enabling/disabling PDF, ePub or "Single HTML" builds. So we can't provide any custom download format through this interface (otherwise we'd just upload a "Standalone HTML" build, which is the exact same as the live online version).

[Bruce200]

Since this would be in a Kindle book format, we could put it up on the Kindle store for free. Unless there is some agreement with ReadTheDocs that we can't put our docs anywhere else?
I've already explained it in a different issue that was closed, but having it on the Kindle bookstore allows it to be read on a ton of devices.

[Bruce200]

I can't begin working on any sort of generator right away, as I'm on vacation and will be back soon, but I did find something about converting HTML to a Kindle book here. Amazon does support a ZIP folder with HTML files and all the images you need as a way to make you e-book.

[botteu]

Really cool that you're looking into this! I just want to say that I'm aware that this is a community-driven and I'm extremely thankful to everybody involved and I'm not saying that this is an important issue by any stretch. I just saw the ePub-link and tried it. The plan was to convert it to Kindle's mobi-format, so if it's possible to publish on Kindle store that would be truly great. But I realize that there are more pressing matters :)