Fix broken ePub documentation by adding a proper theme for it
|Reported by:||Markus Amalthea Magnuson||Owned by:||nobody|
|Has patch:||yes||Needs documentation:||no|
|Needs tests:||no||Patch needs improvement:||yes|
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.