Create ePub versions of PEPs

[AA-Turner]

cc: @Mariatta @froi

I know that we can generate ePub using Sphinx. Is that something we can get if we're going with GitHub pages?

Originally posted by @Mariatta in #1933 (comment)

Note that ePubs is somewhat dependent on the Sphinx work (#2)

[AA-Turner]

Resources (no idea how useful, for future me):

https://www.sphinx-doc.org/en/master/faq.html#epub-info
https://www.sphinx-doc.org/en/master/usage/builders/index.html#sphinx.builders.epub3.Epub3Builder

https://publishdrive.zendesk.com/hc/en-us/articles/115003164334-How-do-I-check-my-ebook-Preview-of-book-epub-file-

[Mariatta]

Thanks. ReadTheDocs can also handle the ePub generation. It is a built-in feature on their side:
https://docs.readthedocs.io/en/stable/downloadable-documentation.html

[AA-Turner]

As a design decision, would 1 massive epub file (~5,500 pages), or individual files per PEP be preferred?

@froi would be interested in your views as an epub user?

A

[AA-Turner]

Gotten an initial implementation working, although unstyled (I don't know if ePubs are expected to be styled to parity with HTML?) and with one error (literal/code blocks overlapping with body text). xref #1995

I am not sure if read the docs would be able to handle this out of the box, as I've customised Sphinx significantly for PEP purposes, disabling the native index, search, javascript, permalinking, etc. As of this, a lot of the stuff Sphinx expects for just changing the builder name to work doesn't exist (e.g. I had to turn off the custom templates I've done for the HTML variant as they fail with epub).

Just my two pennies' worth, but it may turn out that ePub support is as complicated as the custom HTML - adding a lot of potential maintenence burden for a historically low change infrastructure piece? I will continue to work on it but wanted to (constructively!) raise the challenge now as I think about it.

A

[AA-Turner]

Easier than anticpated, have now got the PEP ePub styled to (near) parity with the HTML, and sorted out the code literals issue.

[AA-Turner]

See closure message at #1995