Epub cannot be read

[mwebber]

I downloaded the 1.4 epub, as linked to from http://docs.pylonsproject.org/en/latest/docs/pyramid.html (which, by the way, incorrectly says that 1.4 is still alpha/beta, which I don't think is correct).

The pyramid.epub file cannot be read, at least by the e-reader I am using. If you upload the file to http://validator.idpf.org/, it reports lots of validation errors. I suspect that there is something wrong with the epub build.

[stevepiercy]

I confirm this issue is present when doing make epub to build the epub version of the docs.

This may be due to the focus on non-book versions of the docs. Perhaps @mcdonc knows more.

However it is most likely an issue with Sphinx 1.1.3, as they readily admit that epub output is suboptimal.

Sphinx 1.2 beta1 is out.
http://sphinx-doc.org/latest/changes.html#release-1-2-beta1-released-mar-31-2013

And Roland Meister has an epub branch that is on the bleeding edge, although there are still some reported issues with epub validation.
https://bitbucket.org/rolmei/sphinx-epub

I'd suggest keeping this issue open, even though the issue is not within Pyramid itself, so that we have easy access to history and can refer to the proper project and its status.

[Themanwithoutaplan]

The errors look fairly basic but are too extensive just to list here. Unfortunately, the validator does not persist reports. And, because you can't upload normal files to issue trackers I've put the report on my Dropbox: https://dl.dropboxusercontent.com/u/27484022/epub_validation_report.xlsx (it's just a table).

Sample errors: value of attribute "unique-identifier" is invalid; must be an XML name without colons and then lots and lots of assertion failed: The "id" attribute does not have a unique value

[sontek]

I've verified that using sphinx 1.2.3 fixes the build, so this is a quick one that @stevepiercy could push out to all our branches pretty quickly

[stevepiercy]

Requiring Sphinx 1.2.3 would also fix #669. See http://sphinx-doc.org/changes.html?highlight=changes#release-1-2-3-released-sep-1-2014 and https://bitbucket.org/birkenfeld/sphinx/issue/1239/add-option-to-disable-transformation-of

I've had 1.2.3 installed in my venv for a while so I'm confident that we should set that as the minimum requirement. I'm not sure how to do that for RTD. I'm going to try adding a minimum requirement in setup.py:

    'Sphinx >= 1.2.3',

then push it and see if that kicks RTD up from 1.2.2 on master. Fingers crossed.

[stevepiercy]

Meh. My PR #1501 didn't work. Anyone know how to force RTD to use Sphinx >= 1.2.3? I'm not one of the Owners so I can't see which buttons to push. @cguardia @mcdonc @mmerickel @blaflamme @goodwillcoding do any of you know how to do this?

[stevepiercy]

Fixed in #1502 and #1505