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

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 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

A stab at ePub support (xref #1994).

Previewing on a desktop app (adobe digital editions) everything looks fine apart from code blocks (e.g. page 66), so will have a look at overriding the CSS.

Test: make sphinx-epub and look at build/PEPs.epub. This is the one massive file for all PEPs approach, which is the default from the Sphinx ePub 3 writer -- if a per-PEP solution were wanted, I imagine this may be tricker.

cc: @froi, @Mariatta

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

The intention with using pages was so previews on forks (to <user>.github.io/peps) worked out of the box - although I admit I haven't written that part of the GHA script yet. This was originally discussed in #25 I think.

A

Not sure who gets to decide on this, but I'd like for us to create a readthedocs project so we can preview @AA-Turner's PRs in ReadTheDocs. What do folks think?

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

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

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 https://github.com/python/peps/pull/1933#issuecomment-864294524

Hi Mariatta,

Thanks for the feedback :)

Will have a look at ePubs, although I don't have a kindle so I don't think I can preview? (after writing this I'll probably find an epub app for my phone within 30 seconds!)

Could I suggest though that it's tackled in a separate PR? Currently I'm focussed on trying to replicate what we currently have - but appreciate moving to Sphinx opens more avenues, which is partly the point I guess! I will open an issue to track ePub generation.

A

Just wanted to mention that I took a quick look at https://aa-turner.github.io/peps/ and it looks pretty cool.

I know that we can generate ePub using Sphinx. Is that something we can get if we're going with GitHub pages? I know that it is something we can get easily if hosting it in readthedocs.

cc @froi who was wondering about ePub version of the PEPs.

@pablogsal - rebased on master, I summarised changes above but can provide more detail if you'd like on anything :)

Do you know who best to contact to get GH pages enabled on this repo, incidentally?

A

https://github.com/mheap/automatic-approve-action should in theory auto-approve builds from new maintainers that don't change the workflow. However, there's an issue with the Github API and some repos (including this one). https://github.com/mheap/automatic-approve-action/issues/9 describes the issue, and @cschleiden is apparently looking into the issue.

@luciusmagn After this gets merged we should hopefully be able to enable the "Rust build must be green to merge" and "branch must be up-to-date with master" (the latter needs the former) in Settings (see https://github.com/rust-unofficial/awesome-rust/settings/branch_protection_rules/15609230) and stop the issues from #1096 happening again as the errors were unrelated, but if master had been merged it would have had some related errors!

Fixes the issues from #1096 as well as prost rename.

Perhaps we should create requirements.txt and pin the versions ofdocutils and pygments.

Thanks for the reviews.

It currently looks kinda odd.

Though I'm not sure of the original intention. Which part does the author want to be linked?

Built locally after removing the space between the s and the first grave accent and can confirm it renders as I hypothesised above.

Would this also be fixed by removing the space between the s and the first grave accent? That would make a grad student's render in italic and then $PYTHONSTARTUP render as code.

With your current change I think the grave accent on line 868 should also be removed (before a), as else you have an unclosed start of an italic passage.

Ok, it looks like it has to be right after Authors.

Hmm, I'm not sure what's the issue.. Looking at the template at PEP 12, It shows "discussions-to" to be before Created and before Type