Skip to main content

Tool to convert epub to ReST for Sphinx

Project description


epub2sphinx is a tool to convert epub files directly into HTML sites using Pandoc and Sphinx. It can use any of pre-existing Sphinx themes (like these) for the generated HTML site.

It uses Pandoc for converting HTML data inside epub files into ReST files and then uses Sphinx to convert them into a HTML site.

It creates a directory structure similar to what sphinx-quickstart generates by default.

Built during FOSSHack 21 to solve this issue.


  • Install pandoc

    # On Ubuntu
    sudo apt-get install pandoc
    # On Arch Linux
    pacman -S pandoc

    For installing on other platforms, look here.

  • Install epub2sphinx

    pip install epub2sphinx


Usage: epub2sphinx <epub_file_name> [-o <output_directory_path>] [-t <sphinx_theme_name>] [-b,--build|-B,--no-build] [-s|--serve] [-c] [-p <port_number>]

  This tool helps you to convert your epub files into sphinx format for a better reading experience.
  Kindly provide the epub file as the argument to this command.

  -o, --output-directory PATH   The name of the output directory where the ReST file will be generated.
                                Kindly make sure that the given directory is not existing already.
  -t, --theme TEXT              The name of the sphinx theme.You can check for the available themes at:
  -b, --build / -B, --no-build  Build HTML from the generated ReST files using Sphinx.
                                Sphinx has to be installed for this to work.  [default: b]
  -s, --serve                   Build HTML using Sphinx and Serve the files on localhost.
                                Sphinx has to be installed for this to work.
  -c, --include-custom-css      Include the custom CSS and Fonts from the EPUB for the HTML output
  --overwrite                   Overwrite the output directory if present already
  -p, --port INTEGER            The port number on which the files will be served after conversion
  --version                     Show the version and exit.
  --help                        Show this message and exit.


epub2sphinx -o out_dir -t classic my_book.epub

# To generate HTML files using Sphinx
cd out_dir
make html


epub2sphinx can be used to convert public domain or CC-licensed epub files into static web pages that allows people to read them online. This will be useful for sites like Project Gutenberg or FreeTamilEbooks. Eventhough Project Gutenberg has an option to read online, it is very plain. Using Sphinx allows us to make use of any default or custom sphinx theme to make it look better.

Screenshots of comparison

Project Gutenberg online read vs Sphinx generated output




Contributions are welcome. Fork the repo and Create a PR with your changes. If you are working on any of the existing issues, please add a comment on the issue to avoid duplicated effort.

GitHub GitHub issues GitHub forks GitHub Repo stars GitHub watchers

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

epub2sphinx-0.0.5.tar.gz (12.4 kB view hashes)

Uploaded Source

Built Distribution

epub2sphinx-0.0.5-py3-none-any.whl (14.8 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page