[Django] #21190: Fix broken ePub documentation by adding a proper theme for it
Django
---------------------------------+--------------------
Reporter: giuliettamasina | Owner: nobody
Type: New feature | Status: new
Component: Documentation | Version: 1.5
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Easy pickings: 0 | UI/UX: 0
---------------------------------+--------------------
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].
--
Ticket URL: <https://code.djangoproject.com/ticket/21190>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
Reporter: giuliettamasina | Owner: nobody
Type: New feature | Status: new
Component: Documentation | Version: 1.5
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by EvilDMP):
* needs_better_patch: => 0
* needs_docs: => 0
* needs_tests: => 0
* stage: Unreviewed => Accepted
--
Ticket URL: <https://code.djangoproject.com/ticket/21190#comment:1>
Django
Reporter: giuliettamasina | Owner: nobody
Type: New feature | Status: new
Component: Documentation | Version: 1.5
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (by giuliettamasina):
Has anyone had time to look at this?
--
Ticket URL: <https://code.djangoproject.com/ticket/21190#comment:2>
Django
Reporter: giuliettamasina | Owner: nobody
Type: New feature | Status: new
Component: Documentation | Version: 1.5
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by timo):
* has_patch: 0 => 1
Comment:
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.
--
Ticket URL: <https://code.djangoproject.com/ticket/21190#comment:3>
Django
Reporter: giuliettamasina | Owner: nobody
Type: New feature | Status: new
Component: Documentation | Version: 1.5
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (by aaugustin):
This contribution really looks like it should go to Read The Docs.
--
Ticket URL: <https://code.djangoproject.com/ticket/21190#comment:4>
Django
Reporter: giuliettamasina | Owner: nobody
Type: New feature | Status: new
Component: Documentation | Version: 1.5
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (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.
--
Ticket URL: <https://code.djangoproject.com/ticket/21190#comment:5>
Django
Reporter: giuliettamasina | Owner: nobody
Type: New feature | Status: new
Component: Documentation | Version: 1.5
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (by aaugustin):
OK. I read the patch too quickly. Sorry.
--
Ticket URL: <https://code.djangoproject.com/ticket/21190#comment:6>
Django
Reporter: giuliettamasina | Owner: nobody
Type: New feature | Status: new
Component: Documentation | Version: 1.5
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (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.)
--
Ticket URL: <https://code.djangoproject.com/ticket/21190#comment:7>
Django
Reporter: giuliettamasina | Owner: nobody
Type: New feature | Status: new
Component: Documentation | Version: 1.5
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (by timo):
Yes, see comment 3 above for my suggestions on how to move this forward.
--
Ticket URL: <https://code.djangoproject.com/ticket/21190#comment:8>
Django
Reporter: giuliettamasina | Owner: nobody
Type: New feature | Status: new
Component: Documentation | Version: 1.5
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (by giuliettamasina):
I've now opened a pull request for this:
https://github.com/django/django/pull/2101
--
Ticket URL: <https://code.djangoproject.com/ticket/21190#comment:9>
Django
Reporter: giuliettamasina | Owner: nobody
Type: New feature | Status: new
Component: Documentation | Version: 1.5
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (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.).
--
Ticket URL: <https://code.djangoproject.com/ticket/21190#comment:10>
Django
Reporter: giuliettamasina | Owner: nobody
Type: New feature | Status: new
Component: Documentation | Version: 1.5
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (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.
--
Ticket URL: <https://code.djangoproject.com/ticket/21190#comment:11>
Django
Reporter: giuliettamasina | Owner: nobody
Type: New feature | Status: new
Component: Documentation | Version: 1.5
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Changes (by timo):
* needs_better_patch: 0 => 1
Comment:
Added some minor comments for improvements on the PR.
--
Ticket URL: <https://code.djangoproject.com/ticket/21190#comment:12>
Django
Reporter: giuliettamasina | Owner: nobody
Type: New feature | Status: new
Component: Documentation | Version: 1.5
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Comment (by anonymous):
Updated the pull request with the suggested improvements.
--
Ticket URL: <https://code.djangoproject.com/ticket/21190#comment:13>
Django
Reporter: giuliettamasina | Owner: nobody
Type: New feature | Status: new
Component: Documentation | Version: 1.5
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Comment (by giuliettamasina):
That last comment was by me :)
--
Ticket URL: <https://code.djangoproject.com/ticket/21190#comment:14>
Django
Reporter: giuliettamasina | Owner: nobody
Type: New feature | Status: closed
Component: Documentation | Version: 1.5
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Changes (by Tim Graham <timograham@…>):
* status: new => closed
* resolution: => fixed
Comment:
In [changeset:"59d9b264745bb1a4736bb6df4dafb83049835483"]:
{{{
#!CommitTicketReference repository=""
revision="59d9b264745bb1a4736bb6df4dafb83049835483"
Fixed #21190 -- Added a new ePub theme for documentation.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/21190#comment:15>