Making my first e-book

Now that I got an EPUB reader, I started looking for a way to make EPUB documents.

In principle, an EPUB file is a zipfile with a certain layout, as can be seen on the wikipedia page linked above.

The actual contents are just XHTML, while the metadata files are XML. While it would be possible to edit these by hand, this is cumbersome. I prefer to write in a format like (preferably) reStructuredText or markdown.

Python uses sphinx to generate documentation from reStructuredText. It can generate HTML, PDF (via LaTeX), UNIX manual pages and EPUB.

The primary goal for sphinx is to generate documentation for modules and programs written in Python. But with some tinkering this program can also ouput general EPUB books.

As a test I “ported” my sound filtering post to an ebook.

For a sample document, I used sphinx-quickstart to generate a directory structure:

slackbox:~> cd tmp/bar
slackbox:~/tmp/bar> sphinx-quickstart --epub --no-batchfile
Welcome to the Sphinx 4.3.1 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Selected root path: .

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]:

The project name will occur in several places in the built documentation.
> Project name: Test
> Author name(s): Roland Smith
> Project release []: 1.0

If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> Project language [en]:

Creating file /home/rsmith/tmp/bar/conf.py.
Creating file /home/rsmith/tmp/bar/index.rst.
Creating file /home/rsmith/tmp/bar/Makefile.

Finished: An initial directory structure has been created.

You should now populate your master file /home/rsmith/tmp/bar/index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

This resulted in the following files:

.
├── _build
├── _static
├── _templates
├── conf.py
├── index.rst
└── Makefile

I edited the provided conf.py script to suit the production of an EPUB. Additionally I specified a cover page with some text but without a cover image. To do that I copied the cover template from site-packages/sphinx/themes/epub to the _templates directory and modified it.

# -- Project information -----------------------------------------------------
project = "Sound filtering with Python"
copyright = "2022, Roland Smith"
author = "Roland Smith"
# The full version, including alpha/beta/rc tags
release = "1.0"

# -- General configuration ---------------------------------------------------
extensions = []
templates_path = ["_templates"]
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]

# -- Options for HTML output -------------------------------------------------
html_static_path = ["_static"]

# -- Additions by R.F. Smith ------------------------------------------------
epub_publisher = author
version = release
html_title = project
epub_scheme = "UUID"
# Generate identifier with uuid.uuid4().
epub_identifier = "68538075-d11e-11e2-a29e-001e8ca67578"
epub_uid = "pub-id"
epub_tocdepth = 2
epub_tocdup = False
epub_cover = ("", "epub-cover-RS.html")
html_use_index = False
html_use_smartypants = True
html_show_sourcelink = False

Additionally, I rewrote the Makefile to remove all rules that weren’t needed for the epub build. What is left is:

# Makefile for Sphinx documentation

SPHINXBUILD   := sphinx-build
SRCDIR        := .
BUILDDIR      := _build

# Internal variables.
ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees .

.PHONY: help clean epub

help:
        @echo "Please use \`make <target>' where <target> is one of"
        @echo "  epub       to make an epub"
        @echo "  clean      to remove the contents of _build"

clean:
        -rm -rf $(BUILDDIR)/*

epub:
        $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub

The resulting EPUB file is SoundfilteringwithPython.epub

For comments, please send me an e-mail.

← Unicode characters Moving scripts to a private repo →

Roland's homepage

Making my first e-book

Related articles