search

cdsleiden / python-tutorial

Beginner's introduction to programming in Python
https://cdsleiden.github.io/python-tutorial/
3 stars 2 forks source link

Automatically create EPUB #11

Open bencomp opened 2 years ago

bencomp commented 2 years ago

Similar to but easier than #10 is creating an EPUB file containing all course materials. We don't need a lot of extras for this to work, although an initial build didn't include the majority of content. This may have to do with the headings not being nested properly.

bencomp commented 2 years ago

I spent some time to figure out why in the basic EPUB build not all pages were visible and broken internal references were created (idrefs pointing to non-existing ids in XML). I couldn't find an issue that is really about this in the Jupyter Book and Sphinx repositories. Based on Epubchecker's validation results, I wondered if it could be related to spaces in the filenames.

Removing all spaces from filenames and references in the TOC seemed to have cleared that problem. Other issues found by Epubchecker were bad HTML (tables within paragraphs and width attributes on table and td elements). After fixing that the layout of tables will be a little different, but there are far fewer errors. Apple Books shows all the chapters, although all the contents is in a single chapter called "Welcome", i.e. the root document.

bencomp commented 2 years ago

I noticed that unspecified metadata is added to the EPUB as unknown: description, contributor and identifiers. The EPUB specification for <metadata> explains that some of these are optional elements and some are repeatable. Having "Peter and Ben" in one creator element is not recommended.

Of course this is not too important.