How to Write a Book with Python and Sphinx

Ezz El Din Abdullah
Sep 8 · 7 min read
Image for post
Image for post
Photo by Theme Inn on Unsplash

What is Sphinx?

Sphinx is a documentation generator library which can be useful to generate documentation for your project and can also be used for creating a content (e.g. a book) in a LaTeX and then can be converted to PDF format.‍

Sphinx Installation

Whether you use macOS, Linux, or Windows you can install it with this command:

$ pip install -U sphinx

Sphinx Quickstart

Let’s first make sure sphinx is installed by showing its version:

$ sphinx-quickstart --version
$ mkdir sphinx-tutorial && cd sphinx-tutorial
$ sphinx-quickstart

Sphinx Configuration

Let’s see the configurations we’ve done so far by opening config.py in the source directory:

Building Sphinx

Let’s build the documentation and see what we can get in the build directory and what our sphinx quickstart boilerplate look like in the web:

$ sphinx-build source/ build/
Running Sphinx v3.2.1
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: [new config] 1 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
generating indices... genindexdone
writing additional pages... searchdone
copying static files... ... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded.
The HTML pages are in build.
├── build
│ ├── _sources
│ │ └── index.rst.txt
│ ├── _static
│ │ ├── alabaster.css
│ │ ├── basic.css
│ │ ├── custom.css
│ │ ├── doctools.js
│ │ ├── documentation_options.js
│ │ ├── file.png
│ │ ├── jquery-3.5.1.js
│ │ ├── jquery.js
│ │ ├── language_data.js
│ │ ├── minus.png
│ │ ├── plus.png
│ │ ├── pygments.css
│ │ ├── searchtools.js
│ │ ├── underscore-1.3.1.js
│ │ └── underscore.js
│ ├── genindex.html
│ ├── index.html
│ ├── objects.inv
│ ├── search.html
│ └── searchindex.js
$ open build/index.html
$ xdg-open build/index.html
$ start build/index.html
Image for post
Image for post
sphinx quickstart webpage

Editing reStructuredText

reStructuredText is a markup language designed to be simple and unobtrusive. It uses consistent patterns interpreted by an HTML converter to produce ‘Very Structured Text’ that can be used by a web browser. Its format is .rst

.. myproject documentation master file, created by
sphinx-quickstart on Sat Aug 29 14:31:34 2020.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to myproject's documentation!
=====================================
.. toctree::
:maxdepth: 2
:caption: Contents:
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
* :ref:`genindex`
* :ref:`modindex`
$ sphinx-build source/ build/
Image for post
Image for post
sphinx documentation without indexes
.. toctree::
:maxdepth: 2
:caption: Contents:
codeforces
└── source
├── _static
├── _templates
├── codeforces.rst
├── conf.py
└── index.rst

Rendering Math Equations

If you happen to see happy number, a medium leetcode problem that I put on my blog .. you’ll see it has some mathematical formulas there — simple ones .. let’s see how we can render math equations in reStructuredText.

extensions = ['sphinx.ext.mathjax']
.. myproject documentation master file, created by
sphinx-quickstart on Sat Aug 29 14:31:34 2020.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to myproject's documentation!
=====================================
.. toctree::
:maxdepth: 2
:caption: Contents:
codeforces
leetcode
Indices and tables
==================
* :ref:`search`
Image for post
Image for post
sphinx documentation with mathematical formulas and code-blocks

Converting reStructuredText to PDF

At some point, we would like to convert that RST documentation into PDF. Before we build, we need to configure that in the extension so we add rst2pdf.pdfbuilder so now the extension list look like this:

extensions = ['sphinx.ext.mathjax', 'rst2pdf.pdfbuilder']
$ sphinx-build -b pdf source/ build/
$ pip install rst2pdf

Conclusion

Now, you can use python and sphinx to build a documentation for your project with table of contents and you can use hyperlinks, headings, images, mathematical formulas, syntax highlighting for whatever programming languages you like, and more.

References

The Innovation

Entrepreneurship, Innovation, Design Thinking, Sustainability & Creativity

Sign up for The Innovation Digest

By The Innovation

Official newsletter of The Innovation Take a look

By signing up, you will create a Medium account if you don’t already have one. Review our Privacy Policy for more information about our privacy practices.

Check your inbox
Medium sent you an email at to complete your subscription.

Ezz El Din Abdullah

Written by

Data Engineer | I write at ezzeddinabdullah.com

The Innovation

Entrepreneurship, Innovation, Design Thinking, Sustainability & Creativity

Ezz El Din Abdullah

Written by

Data Engineer | I write at ezzeddinabdullah.com

The Innovation

Entrepreneurship, Innovation, Design Thinking, Sustainability & Creativity

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store