id summary reporter owner description type status component version severity resolution keywords cc stage has_patch needs_docs needs_tests needs_better_patch easy ui_ux 21190 Fix broken ePub documentation by adding a proper theme for it Markus Amalthea Magnuson nobody "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` [https://bitbucket.org/birkenfeld/sphinx/commits/e4475038e1ffa79dde932664a2259df783bed668 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 [http://www.adobe.com/se/products/digital-editions.html Adobe Digital Editions]." New feature closed Documentation 1.5 Normal fixed Accepted 1 0 0 1 0 0