# How to Write a Book with Python and Sphinx

Sep 8 · 7 min read

# 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.1building [mo]: targets for 0 po files that are out of datebuilding [html]: targets for 1 source files that are out of dateupdating environment: [new config] 1 added, 0 changed, 0 removedreading sources... [100%] index looking for now-outdated files... none foundpickling environment... donechecking consistency... donepreparing documents... donewriting output... [100%] index generating indices... genindexdonewriting additional pages... searchdonecopying static files... ... donecopying extra files... donedumping search index in English (code: en)... donedumping object inventory... donebuild 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

# 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/ .. 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 leetcodeIndices and tables==================* :ref:search # 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

### By The Innovation

Official newsletter of The Innovation Take a look

Written by

Written by