Roland's homepage

My random knot in the Web

Making my first EPUB

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
Welcome to the Sphinx 1.1.3 quickstart utility.

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

Enter the root path for documentation.
> Root path for the documentation [.]:

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

Inside the root directory, two more directories will be created; "_templates"
for custom HTML templates and "_static" for custom stylesheets and other static
files. You can enter another prefix (such as ".") to replace the underscore.
> Name prefix for templates and static dir [_]:

The project name will occur in several places in the built documentation.
> Project name: This is a test
> Author name(s): Roland Smith

Sphinx has the notion of a "version" and a "release" for the
software. Each version can have multiple releases. For example, for
Python the version is something like 2.5 or 3.0, while the release is
something like 2.5.1 or 3.0a1.  If you don't need this dual structure,
just set both to the same value.
> Project version: 1.0

The file name suffix for source files. Commonly, this is either ".txt"
or ".rst".  Only files with this suffix are considered documents.
> Source file suffix [.rst]:

One document is special in that it is considered the top node of the
"contents tree", that is, it is the root of the hierarchical structure
of the documents. Normally, this is "index", but if your "index"
document is a custom template, you can also set this to another filename.
> Name of your master document (without suffix) [index]:

Sphinx can also add configuration for epub output:
> Do you want to use the epub builder (y/N) [n]: y

Please indicate if you want to use one of the following Sphinx extensions:
> autodoc: automatically insert docstrings from modules (y/N) [n]:
> doctest: automatically test code snippets in doctest blocks (y/N) [n]:
> intersphinx: link between Sphinx documentation of different projects (y/N) [n]:
> todo: write "todo" entries that can be shown or hidden on build (y/N) [n]:
> coverage: checks for documentation coverage (y/N) [n]:
> pngmath: include math, rendered as PNG images (y/N) [n]:
> mathjax: include math, rendered in the browser by MathJax (y/N) [n]:
> ifconfig: conditional inclusion of content based on config values (y/N) [n]:
> viewcode: include links to the source code of documented Python objects (y/N) [n]:

A Makefile and a Windows command file can be generated for you so that you
only have to run e.g. `make html' instead of invoking sphinx-build
> Create Makefile? (Y/n) [y]:
> Create Windows command file? (Y/n) [y]: n

Creating file ./
Creating file ./index.rst.
Creating file ./Makefile.

Finished: An initial directory structure has been created.

You should now populate your master file ./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.

I edited the provided script to suit the production of an EPUB.

The sections that affected outputs other than HTML and epub were removed.

The options html_use_index, html_show_sourcelink, html_show_sphinx = False, html_show_copyright and epub_tocdup were set to False to switch them off.

The option html_use_smartypants to convert quotes and dashes to their typographically correct entities was switched on.

Additionally I specified a cover page with some text but without a cover image. To do that I copied the cover template to the _templates directory and modified it.

# -- General configuration ------------------------------------------------
extensions = []
templates_path = ['_templates']
source_suffix = '.rst'
master_doc = 'index'
project = u'Sound filtering with Python'
copyright = u'2013, Roland Smith'
version = '1.0'
release = version
language = 'en'
exclude_patterns = ['_build']

# -- Options for HTML output ---------------------------------------------
html_theme = 'epub'
html_title =  project
#html_short_title = None
html_static_path = ['_static']
html_use_smartypants = True
html_use_index = False
html_show_sourcelink = False
html_show_sphinx = False
html_show_copyright = False
html_use_opensearch = ''
htmlhelp_basename = 'SoundfilteringwithPython'

# -- Options for Epub output -------------------------------------------
epub_author = u'Roland Smith'
epub_publisher = u'Roland Smith'
epub_scheme = 'UUID'
epub_identifier = '68538075-d11e-11e2-a29e-001e8ca67578'
epub_uid = epub_identifier
epub_cover = ('', 'epub-cover-RS.html')
epub_tocdepth = 2
epub_tocdup = False
epub_exclude_files = ['_static/opensearch.xml', '_static/doctools.js',
'_static/jquery.js', '_static/searchtools.js', '_static/underscore.js',
'_static/basic.css', 'search.html', '_static/websupport.js']

Additionally, I trimmed 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
PAPER         =
BUILDDIR      = _build

# Internal variables.
PAPEROPT_a4     = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
# the i18n builder cannot share the environment and doctrees with the others

.PHONY: help clean epub

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

        -rm -rf $(BUILDDIR)/*

        $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
        @echo "Build finished. The epub file is in $(BUILDDIR)/epub."

The resulting EPUB file is SoundfilteringwithPython.epub

←  Me at work Computer control, mature nor secure?  →