Opened 3 years ago

Closed 2 years ago

#21190 closed New feature (fixed)

Fix broken ePub documentation by adding a proper theme for it

Reported by: giuliettamasina Owned by: nobody
Component: Documentation Version: 1.5
Severity: Normal Keywords:
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: yes
Easy pickings: no UI/UX: no


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:

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 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 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.

Attachments (1)

broken_django_epub.png (73.7 KB) - added by giuliettamasina 3 years ago.
The current ePub version of the documentation is broken.

Download all attachments as: .zip

Change History (16)

Changed 3 years ago by giuliettamasina

The current ePub version of the documentation is broken.

comment:1 Changed 3 years ago by EvilDMP

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Triage Stage changed from Unreviewed to Accepted

comment:2 Changed 3 years ago by giuliettamasina

Has anyone had time to look at this?

comment:3 Changed 3 years ago by timo

  • Has patch set

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,, 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.

comment:4 Changed 3 years ago by aaugustin

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

comment:5 Changed 3 years ago by giuliettamasina

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.

comment:6 Changed 3 years ago by aaugustin

OK. I read the patch too quickly. Sorry.

comment:7 Changed 2 years ago by giuliettamasina

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.)

comment:8 Changed 2 years ago by timo

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

comment:9 Changed 2 years ago by giuliettamasina

I've now opened a pull request for this:

comment:10 Changed 2 years ago by ramiro

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.).

comment:11 Changed 2 years ago by giuliettamasina

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.

comment:12 Changed 2 years ago by timo

  • Patch needs improvement set

Added some minor comments for improvements on the PR.

comment:13 Changed 2 years ago by anonymous

Updated the pull request with the suggested improvements.

comment:14 Changed 2 years ago by giuliettamasina

That last comment was by me :)

comment:15 Changed 2 years ago by Tim Graham <timograham@…>

  • Resolution set to fixed
  • Status changed from new to closed

In 59d9b264745bb1a4736bb6df4dafb83049835483:

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

Note: See TracTickets for help on using tickets.
Back to Top