publishing-workshop

Self-publish your book without overhead using Sphinx

Michael McMahon

sphinx-doc is a way to write ebooks, documentation, or websites once and export to your desired output. Exported formats include epub, html, pdf, etc.

Copyright © Michael McMahon 2019. Except where otherwise specified, the text on publishing-workshop by Michael McMahon is licensed under the Creative Commons Attribution-ShareAlike License 4.0 (International) (CC-BY-SA 4.0).

Contributing to publishing-workshop

We would love to hear from you! Create New Issues with questions, problems, or solutions.

See the CONTRIBUTING.md file for ways to make contributions.

Building publishing-workshop

If you would like to build a custom copy of publishing-workshop, you will need Python, Sphinx, and Calibre.

Directions for installing Sphinx
Open a terminal.
Clone this project.

git clone https://github.com/TechnologyClassroom/publishing-workshop

Edit TechnologyClassroom/source/index.rst
Build the epub file.

sphinx-build -b epub source build

Convert epub to mobi.

ebook-convert build/publishing-workshop.epub build/publishing-workshop.mobi

Open the resulting epub file with calibre.

ebook-viewer build/publishing-workshop.epub

Creating a new sphinx-doc project

Install sphinx-doc according to their documentation. Open a terminal. Navigate to a new directory for your project. Run the sphinx-quickstart program.

sphinx-quickstart

I used these answers:

> Root path for the documentation [.]: .
> Separate source and build directories (y/n) [n]: y
> Name prefix for templates and static dir [_]: _
> Project name: InsertProjectName
> Author name(s): InsertAuthorOrAuthorsHere
> Project version []: 1.0
> Project release [1.0]: 1.0
> Project language [en]: en
> Source file suffix [.rst]: .rst
> Name of your master document (without suffix) [index]: index
> Do you want to use the epub builder (y/n) [n]: y
> autodoc: automatically insert docstrings from modules (y/n) [n]: y
> doctest: automatically test code snippets in doctest blocks (y/n) [n]: n
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]: n
> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: n
> coverage: checks for documentation coverage (y/n) [n]: n
> imgmath: include math, rendered as PNG or SVG images (y/n) [n]: n
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]: n
> ifconfig: conditional inclusion of content based on config values (y/n) [n]: n
> viewcode: include links to the source code of documented Python objects (y/n) [n]: n
> githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]: n
> Create Makefile? (y/n) [y]: y
> Create Windows command file? (y/n) [y]: y

After this the directory trees are created. Edit ./source/index.rst to modify the document.

Build a new epub into the build directory with this command:

sphinx-build -b epub source build

conf.py

config.py epub options

An example conf.py file I have used can be found here.

# epub cover image
epub_cover = ('_static/mr-cover.png', '')

# epub index
epub_use_index = False

# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#
html_show_sphinx = False

Templates

Themes are located in the /usr/share/sphinx/themes/ folder.

The default theme can be found in the /usr/share/sphinx/themes/basic folder.

Templating

Theming at tinkerer.me

Adding creative commons TP from https://groups.google.com/forum/#!topic/sphinx-users/f3Yl45l1KYg suggests overwriting the footer with a template:

Template modifiers can be placed in the file ./source/_templates/layout.html

CC BY-SA 4.0 INTL

{% extends "!layout.html" %}
{%- block footer %}
{{ super() }}
  <div class="footer">
    <span class="creativecommons">
      <a href="https://creativecommons.org/licenses/by-sa/4.0/" >
        <img src="{{ pathto("_static/ccby-sa4.0intl88x31.png", 1) }}"
          alt="Creative Commons License"/></a>
      This work is licensed under a
      <a rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/">
        Creative Commons Attribution-ShareAlike 4.0 International License
      </a>
    </span>
  </div>
{%- endblock %}

Removing the navigation links at the top of each page

{% block relbar1 %}{% endblock %}

Examples

Code Snippets

Adding a picture

.. image:: /_static/picture.png
   :width: 700px
   :align: center

.. end_tag

<h2>3 column time table</h2>

+-----------+------------+----------+
|      Time | Activity   | Notes    |
+===========+============+==========+
|  5-10 min | ...        | ...      |
+-----------+------------+----------+
| 10-15 min | ...        | ...      |
+-----------+------------+----------+
|    15 min | ...        | ...      |
+-----------+------------+----------+
|    40 min | ...        | ...      |
+-----------+------------+----------+
|    10 min | ...        | ...      |
+-----------+------------+----------+

Check links

Make sure all of your links work with this command:

make linkcheck

Linting

Linting can be carried out by doc8.

sudo pip install doc8
doc8 source/index.rst

Troubleshooting

Problem: make latexpdf returns errors about python2.7 and normalize with Debian.

Solution: While making pdfs is experimental, I was able to remove this error by forcing python 3.

Remove all copies of sphinx with python 2.

sudo apt purge python-sphinx
sudo apt purge sphinx-doc
sudo pip uninstall sphinx

Install sphinx with python 3.

sudo apt install python3-sphinx

Change this line in Makefile:

SPHINXBUILD = python -msphinx

to this:

SPHINXBUILD = python3 -msphinx

TechnologyClassroom / publishing-workshop