Fix broken ePub documentation by adding a proper theme for it

[Markus Amalthea Magnuson]

The current ePub version of the Django documentation is broken, see attached screenshot for an example.

I've decided to fix this by adding a proper Sphinx theme specifically for generating the ePub version of the docs.

Initial work-in-progress can be seen here: ​https://github.com/alimony/django/commit/5714485ae3e8ae3f599283e068cc1cd87eadae79

This is a summary of the changes I've made:

I've added a new theme to the _theme folder called djangodocs-epub. It inherits from Sphinx's default epub theme. This new theme is then specified in the ePub settings of conf.py along with some other things, such as cover page. While at it, I also added all available ePub settings, most of them commented out, for future reference. A couple of them were even missing from the conf.py you get from running sphinx-quickstart ​but I fixed that :)

Regarding the CSS, my first thought was to inherit the default CSS and override bits and pieces, but that was not feasible for a few reasons. First, most of it does not apply to ePub so there would be a lot of redundant styles. Second, many ePub publishers consider it good practice to not specify font family, size, line-height, and background and text colors, as this will override any user setting on their device, which is not very nice. As there is currently no way in CSS to reset to user agent default, I went with a completely separate CSS file instead, containing a few fixes to make things work better on ePub. I've put comments in that file for specifics on why the rules look like they do.

The admonition images are currently duplicated in the new ePub theme, as I have not found a way to copy them or inherit them from the default theme. If anyone knows how, let me know, because that would be more DRY.

My ultimate goal of this little project is to be able to generate a Kindle version of the Django documentation, something that I've already done myself to read the docs on the subway :) But I thought others might benefit from something like that. Kindle generation happens from the ePub using Amazon's own proprietary kindlegen tool. I'm not sure if or how Kindle generation could go into the Django codebase; maybe by adding kindle to the Makefile? If you have a better idea, just let me know. In any case, I think it would be nice to offer a Kindle version of the documentation on Django's website.

So, have a look at this and let me know what the next steps should be, if anything needs changing, etc.

If you don't have a physical ebook device, you can try it out using an ePub compatible software such as ​Adobe Digital Editions.

[Markus Amalthea Magnuson]

The current ePub version of the documentation is broken.

[Markus Amalthea Magnuson]

Has anyone had time to look at this?

[Tim Graham]

I've looked a little. I have to say that I am not thrilled with having to add epub specific things since this means another thing to think about when adding new documentation features, but I agree the current version had some issues that would benefit from this.

I don't get the broken behavior on epub readers that I've tried (Calibre on Linux and Stanza on iOS). Some of the broken styles seem to be inserted by the service that builds our epubs, readthedocs.org, so we may want to coordinate with them to resolve some of these issues.

You could probably use symlinks for the documentation images to avoid duplicating them.

If you could send a pull request with your branch, that will make reviewing this easier.

[Aymeric Augustin]

This contribution really looks like it should go to Read The Docs.

[Markus Amalthea Magnuson]

This uses the default ePub theme from Sphinx but overrides things that are specific to the Django documentation. I don't see how that can happen on Read the Docs. For example, the version switcher should be hidden, and the reason it's not is not because of something that can be changed at Read the Docs, but because it's in the Django documentation in the first place.

In other words, Read the Docs can build proper ePub files and probably does so for many projects, but the builds from the Django documentation are broken.

[Aymeric Augustin]

OK. I read the patch too quickly. Sorry.

[Markus Amalthea Magnuson]

So, is anyone interested in making this happen? I'm willing to put more work into this case, given that it will eventually make its way into core.

(If not, I will probably spin it off into some kind of side-project, but I think that's the lesser good way of doing this.)

[Tim Graham]

Yes, see comment 3 above for my suggestions on how to move this forward.

[Markus Amalthea Magnuson]

I've now opened a pull request for this: ​https://github.com/django/django/pull/2101

[Ramiro Morales]

As Tim, when I test the epub versions for master, 1.6.x, and 1.5.x as of now from Read The Docs I don't see:

• The version selector
• That garbage text at the bottom of pages

Tried it with Calibre 1.9.0 on Linux and with Adobe Digital Editions on Windows.

IMHO these were the two most glaring ugly aspects of the initial report and aren't present anymore.

Will test the code of the proposed PR to verify the proposed anhancements (fonts custotomizability, etc.).

[Markus Amalthea Magnuson]

Huh, that's odd. Something must have changed since I opened this ticket, but I haven't figured out what.

So that was the real ugly part, as you point out.

The most important change still in this changeset though, is to keep the max width of code and images within the page width. Currently, code blocks are cut off at the right border and are thus not readable in their entirety.

Other nice features of the changeset are:

• Proper cover page
• Screen estate saving features such as narrower list widths, and hiding print-style absolute URLs after links.
• Use the special styled note/warning box from the default theme, but modified to allow text resizing without breaking.

Note that I've pushed another commit to the branch of that pull request, with a minor padding change to note boxes.

[Tim Graham]

Added some minor comments for improvements on the PR.

[anonymous]

Updated the pull request with the suggested improvements.

[Markus Amalthea Magnuson]

That last comment was by me :)

[Tim Graham <timograham@…>]

In 59d9b264745bb1a4736bb6df4dafb83049835483:

Fixed #21190 -- Added a new ePub theme for documentation.