Sphinx Cookbook

Sphinx is the name of the software application used to build documentation from reStructured text files.

reStructured text is a type of markdown, and reStructured text files have an rst extension. E.g., phoneid.rst.

Sphinx Documentation

For information about how to use Sphinx, see Sphinx Documentation Generator - Documentation Contents

Sphinx Terminology

Before you can become proficient at using Sphinx, you must understand Sphinx-specific terminology.

Source Directory

The Source Directory is the Root Directory of a docset.

E.g., C:\Users\Chris\src\python_rest_api\doc\user\v1\source\

The Source Directory always contains the Sphinx build Sphinx Configuration File - conf.py.

The Configuration File is a data store that contains the set of Sphynx options and customization details for the doc set (for example, the Project Name, and the name and location of the Template you want to use).

The Source Directory also contains the Master File - index.rst.

The Master File is the root topic for your collection. It contains the [/./. toctree::] directive. You list the names of the second-level topics beneath this directive, and it automatically links them into the doc set (and into the table of contents).

For example, the Source Directory for the TeleSign Python SDK project is


Working Directory

The Working directory is one level up from the Source directory.



When you use a Make file to run Sphinx, the file make.bat must reside in the Working Directory.

This directory contains a folder called source, and another folder called build).

Installing Sphinx

  1. Open an Administrative command prompt (not the Python shell) and enter the command: easy_install -U sphinx.

    The install process takes about a minute to complete.


    This procedure assumes you have already installed Python, Minw32, and Easy Install.

Updating your Sphinx Installation

I discovered that if you have already installed Sphinx once and you want to update it, you must update each of Sphinx’s dependencies yourself!

%USERPROFILE%>easy_install -U sphinx
%USERPROFILE%>easy_install -U docutils
%USERPROFILE%>easy_install -U Jinja2
%USERPROFILE%>easy_install -U Pygments
%USERPROFILE%>easy_install -U PIL


GNU Make is a program that simplifies the building process.

Install Make

  1. Download the make installer from Make forf Windows <http://gnuwin32.sourceforge.net/packages/make.htm>_.

    On the landing page, under the heading titled Download, right-click Setup program, and then save the file to your Downloads folder.

  2. Run the Installer as Administrator.

  3. Create a new environment variable

    MAKE_HOME = C:Program Files (x86)GnuWin32

  4. Add it to the Path


    Reboot your computer to make the environment variables take affect.


This is the executable that actually builds the docs.

There are two files with this name: an executable, and a Python script – and you can use either one!

sphinx-build Options

Option Value Description
-b <builder> The builder to use (the default is html).
-a   Write all files. The default is to write only new and changed files.
-E   Don’t use the cached version of the source files. Read all of the original files again.
-t <tag> Include just the blocks with <tag/>. This is for conditionally building.
-d <path> Path for the cached environment and the doctree files (default: outdir/.doctrees).
-c <path> Path where configuration file (conf.py) is located. (default: same as sourcedir).
-C   Use no config file at all. Use the -D options only.
-D <setting=value> Override a particular setting in configuration file.
-A <name=value> Pass a value into the templates. For HTML builder only.
-n   Enable Nit-picky mode - and warn about all missing references.
-N   Do not output in color.
-q   No output on stdout, just warnings on stderr.
-Q   No output at all, not even warnings.
-w <file> Write warnings (and errors) to the specified file.
-W   Turn warnings into errors.
-P   Run Pdb on exception.


To write new and changed files

Omit the -a switch, and omit the filenames.

To write all files

inclde the -a switch.

To write particular files

Include those filenames.

The sphinx-build Executible

The sphinx-build executible calls the Python script to build the python documentation.


sphinx-build Usage

$ sphinx-build [options] sourcedir builddir [filenames]

sphinx-build Example

%USERPROFILE%>sphinx-build [options] sourcedir outdir [filenames...]

The sphinx-build-script Python Script


C:\\Python27\\Scripts\\sphinx-build-script.py [options] sourcedir outdir [filenames...]

Make File Defaults

These are the Sphinx Build Options that Make uses.

E (Environment) - rebuild all files, not just changed files. D (override value in conf.py with this one) = “version=1.0.4”. b (builder name) = “html”


sourcedir = C:\Users\Chris\python_telesign_sdk\doc\. builddir = C:\Users\Chris\python_telesign_sdk\doc\_build\1.0.4\. filenames = not used.

How To

How to Install the TeleSign Python SDK

python setup.py doc:

When you install the TeleSign Python SDK, as part of its install procedure, it calls sphinx-build and it builds the docs.

status = subprocess.call([“sphinx-build”, “-E”, “-D”, “version=%s” % version, “-b”, mode, “doc”, path])

version = “1.0.4” path = “doc/_build/%s” % version mode = “html”


status = subprocess.call([“sphinx-build”, “-E”, “-D”, “version=1.0.4”, “-b”, “html”, “doc”, “doc/_build/1.0.4”])

Build the Docs

You must run make from the directory that contains make.bat

E.g., C:\Users\Chris\src\python_rest_api\doc\user\v1\

This directory is one level above the directory you use for sphinx_build.

This is what is inside make.bat

if "%1" == "html" (
        if errorlevel 1 exit /b 1
        echo.Build finished. The HTML pages are in %BUILDDIR%/html.
        goto end

Running make html

This is what the command output looks like

C:\\Users\\Chris\\src\\python_rest_api\\doc\\user\\v1>make html

Running Sphinx v1.1.3
building [html]: all source files
updating environment: 33 added, 0 changed, 0 removed

reading sources... [  3%] content/about-rest-api
reading sources... [  6%] content/auth-examples
reading sources... [  9%] content/auth-headers
reading sources... [ 12%] content/canonicalization
reading sources... [ 15%] content/phoneid
reading sources... [ 18%] content/phoneid-contact
reading sources... [ 21%] content/phoneid-live
reading sources... [ 24%] content/phoneid-score
reading sources... [ 27%] content/phoneid-standard
reading sources... [ 30%] content/positional
reading sources... [ 33%] content/reference
reading sources... [ 36%] content/requests
reading sources... [ 39%] content/responses
reading sources... [ 42%] content/rest-auth
reading sources... [ 45%] content/telesign-resources
reading sources... [ 48%] content/time-stamp
reading sources... [ 51%] content/using-the-api
reading sources... [ 54%] content/verify
reading sources... [ 57%] content/verify-call
reading sources... [ 60%] content/verify-sms
reading sources... [ 63%] content/xt/xt-cleansing-codes
reading sources... [ 66%] content/xt/xt-country-codes
reading sources... [ 69%] content/xt/xt-error-codes
reading sources... [ 72%] content/xt/xt-http-response-status-codes
reading sources... [ 75%] content/xt/xt-language-tags
reading sources... [ 78%] content/xt/xt-phone-type-codes
reading sources... [ 81%] content/xt/xt-score
reading sources... [ 84%] content/xt/xt-time-zones
reading sources... [ 87%] content/xt/xt-transaction-codes
reading sources... [ 90%] content/xt/xt-use-case-codes
reading sources... [ 93%] content/xt/xt-verify-status-call
reading sources... [ 96%] content/xt/xt-verify-status-sms
reading sources... [100%] index

looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done

writing output... [  3%] content/about-rest-api
writing output... [  6%] content/auth-examples
writing output... [  9%] content/auth-headers
writing output... [ 12%] content/canonicalization
writing output... [ 15%] content/phoneid
writing output... [ 18%] content/phoneid-contact
writing output... [ 21%] content/phoneid-live
writing output... [ 24%] content/phoneid-score
writing output... [ 27%] content/phoneid-standard
writing output... [ 30%] content/positional
writing output... [ 33%] content/reference
writing output... [ 36%] content/requests
writing output... [ 39%] content/responses
writing output... [ 42%] content/rest-auth
writing output... [ 45%] content/telesign-resources
writing output... [ 48%] content/time-stamp
writing output... [ 51%] content/using-the-api
writing output... [ 54%] content/verify
writing output... [ 57%] content/verify-call
writing output... [ 60%] content/verify-sms
writing output... [ 63%] content/xt/xt-cleansing-codes
writing output... [ 66%] content/xt/xt-country-codes
writing output... [ 69%] content/xt/xt-error-codes
writing output... [ 72%] content/xt/xt-http-response-status-codes
writing output... [ 75%] content/xt/xt-language-tags
writing output... [ 78%] content/xt/xt-phone-type-codes
writing output... [ 81%] content/xt/xt-score
writing output... [ 84%] content/xt/xt-time-zones
writing output... [ 87%] content/xt/xt-transaction-codes
writing output... [ 90%] content/xt/xt-use-case-codes
writing output... [ 93%] content/xt/xt-verify-status-call
writing output... [ 96%] content/xt/xt-verify-status-sms
writing output... [100%] index

writing additional files... genindex search
copying static files... done
dumping search index... done
dumping object inventory... done
build succeeded.

Build finished. The HTML pages are in build/html.

Building Sphinx docs using Sphinxbuild




SPHINXBUILD = sphinx-build builder (-b) = html BUILDDIR = _build

SPHINXOPTS = “”- to match python setup.py doc, this needs -E (rebuild all docs).

cache path (-d) = _build/doctrees - Pickled version of the parsed source files (make.bat does add this option).

= -d _build/doctrees %SPHINXOPTS%


You run sphinx-build from the directory that contains index.rst and conf.py (for example, C:\Users\Chris\src\python_rest_api\doc\user\v1\source).

sphinx-build -b html -E . _build/html

With Tags

sphinx-build -b html -E -t html . _build/

To build a PDF using LaTeX

sphinx-build -b latexpdf -E . _build/pdf

To build a PDF


Don’t try to build the PDF version of the docs because you don’t get good results due to a bug somewhere in Sphinx.

sphinx-build -b pdf -E  . _build/pdf

With Tags

sphinx-build -b pdf -E  -t pdf . _build/pdf

To get Make to work, yhou have to set a value for SPHINXOPTS (it actaully has no value in make.bat!).

To rebuild all files (not just changed files)


For the Python SDK Docs, to see the revisions that you made in api.py, you have to re-install the SDK, and then build the docs.

  1. Open a command prompt. You can use the Git BASH.
  2. Change to the SDK directory (\python_telesign_sdk\).
  3. Reinstall the SDK
python setup.py install
  1. Rebuild the docs
python setup.py doc

reST Reference


.. rubric::
   In this Section


.. toctree::
   :maxdepth: 2



To another topic in the same doc set

You can get the results automatically by subscribing for a :ref:`xref-transaction-callback`.

To a position in the same topic

To a Section Title
`section title`_
To Any Point in the Same Topic

You must first create and place a reference directive immediately before the target content.

Example of Target Reference Directive

.. _xref-verify-2way-sms-resource_uri-object:

Example Usage

After you've made your verification request, you can retrieve the verification results by sending a **GET** request to the ``verify`` resource,  with a :ref:`reference <xref-verify-2way-sms-reference_id-object>` to your original service request for the :ref:`Subresource Identifier <xref-verify-2way-sms-resource_uri-object>`.

An Example of the Resulting HTML URL


To a Web URL

`Link text <http://example.com>`_


".. attention::", ".. caution::", ".. danger::", ".. error::", ".. hint::", ".. important::", ".. note::", ".. tip::", ".. warning::".

Note: only “note” renders with nice formatting.



You must base64 decode it to use in generating the signature.


You can get the results automatically by subscribing for a transaction callback.

Pigment Syntax Coloring


.. highlight:: javascript


.. tag::

The ‘tags’ that are used as switches in the “only::” directive are accessible in the conf.py file with the ‘tags’ object, so you might want to investigate using build command line tags in conjunction with “only::” in your sources, plus a conf.py construction that looks something like this:

if tags.has('modeA'):
   # exclude patterns should throw out any modeB-only files
   exclude_patterns = exclude_patterns + ['modeB_toc.rst']
   master_doc = 'modeA_toc.rst'
else if tags.has('modeB'):
   # exclude patterns should throw out any modeA-only files
   exclude_patterns = exclude_patterns + ['modeA_toc.rst']
   master_doc = 'modeB_toc.rst'
   # some

Building an HTML File From an rst File

Run the rst2html Python script on the rst file.

  1. Open a DOS Command Prompt Window.
  2. Navigate to the directory that contains the REst file you want to convert.
  3. Type rst2html.py \.rst \*.html*.


rst2html.py Readme.rst Readme.html


To get a footer with a link to the source file, date & time of processing, and links to the Docutils project

rst2html.py -stg Readme.rst Readme.html

Donn Trenton’s Original Notes

I Installed Python & the Sphinx Python Documentation Generator.

To build docs

Run the command ‘make html’ from the \doc directory.

The resulting html files are written to this directory


The main web page is the file


Alternatively, you can run this command from the root directory of the telesign source (one up from \doc):

python setup.py doc

The resulting html files are written to this directory:


Doc build directories

For Testing


For Public User Docs


Sphinx build commands

Set up a new build directory

To set up a build for a new documentation set, create a directory to for the doc set.

This should be a subdirectory under /draft (for doc development and testing) or /user (for published docs).

Invoke the following command to set up the source directory, the makefile, and the configuration file:

$ sphinx-quickstart

When you run this command, it asks you a series of questions.

Typically you can accept the defaults, with the following exceptions:

- Autodoc extensions: Y
- Generate makefile: Y (so that you only have to run 'make html' to build)
> Separate source and build directories (y/N): Y (this structure is easier to maintain)
> Source file suffix [.rst or .txt]: .rst (we should decide on a standard)

Build HTML from the current makefile

After you run quickstart, the build is set up, and you can then run the following command to rebuild the docs:

$ make html

The top node contents doc is “index.rst.” If you add new source files to the build, you have to update index.rst.

Rebuild the makefile

If you change the files in your build, you might have to rebuild the makefile. If you’re just adding files you can just add them to index.rst and make build will figure it out. But if you rename files, move, or and remove files it can get confused. To rebuild the makefile, use sphinx-build.

$ sphinx-build -b html source build

List of key quickstart answers


Accept the default value unless otherwise indicated below.

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

The project name will occur in several places in the built documentation.

Project name: TeleSign REST API
Author name(s): TeleSign Corporation

In conf.py, this sets the following:

project = u'TeleSign REST API'
copyright = u'2012, TeleSign Corporation'

Note that “author name” is what appears in the copyright notice.

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:
Project release:

Accept the default, which is no version or release number.

In conf.py, this sets version = ‘’ and release = ‘’.

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

In conf.py, source_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]: index

Please indicate if you want to use one of the following Sphinx extensions:

epub: Do you want to use the epub builder (y/N) [n]: n
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
pngmath: include math, rendered as PNG 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

A Makefile and a Windows command file can be generated for you so that you only have to run make html instead of invoking sphinx-build directly.

Create Makefile? (Y/n) [y]: y
Create Windows command file? (Y/n) [y]: y

After setup creates the config file (conf.py), open the file and change the HTML theme; TeleSign uses the sphinxdoc theme:

Options for HTML output

The theme to use for HTML and HTML Help pages. See the documentation for a list of builtin themes.

html_theme = 'sphinxdoc'


RST – reStructuredText


How do I convert a word document to reStructured text?


An Introduction to reStructuredText



You use Pandoc to convert HTML to RST.


This is especially useful for tables. Create a table in Microsoft Expression Web, switch to code view, copy and paste into an .htm file, then run Pandoc on it to convert it to an .rst file.


pandoc -f html -t rst -o table1.txt table1.htm

To install Pandoc


Pandoc User’s Guide


Pandoc Commands

pandoc -f [from_format] -t [to_format] -o [output_file] [input_file]
pandoc -f docx -t rst -o PVSOAPRST.txt PVSOAPTEST.docx

(this doesn’t work; pandoc doesn’t support conversion from .docx)

pandoc -f html -t rst -o PVSOAPRST1.txt PVSOAPTEST-HTML.htm

(have to save the .docx file as .htm (web page) first)

pandoc -f html -t rst -o PVSOAPRST2.txt PVSOAPTEST-HTML.htm

(have to save the .docx file as .htm (filtered web page) first)

Pandoc Results

C:\\Users\\Donn\\My Documents\\!telesign\\Phone Verification>pandoc -f docx -t rst -o PVSOAPRST.txt PVSOAPTEST.docx
pandoc: Unknown reader: docx
C:\\Users\\Donn\\My Documents\\!telesign\\Phone Verification>pandoc -f html -t rst -o PVSOAPRST1.txt PVSOAPTEST-HTML.htm
pandoc: PVSOAPTEST-HTML.htm: hGetContents: invalid argument (invalid UTF-8 byte sequence)
C:\\Users\\Donn\\My Documents\\!telesign\\Phone Verification>pandoc -f html -t rst -o PVSOAPRST2.txt PVSOAPTEST-HTMF.htm
pandoc: PVSOAPTEST-HTMF.htm: hGetContents: invalid argument (invalid UTF-8 byte sequence)

Advice & Caveats

Line breaks

You can create the source docs in notepad on a Windows computer, but the line breaks are different in Windows vs Linux. I think Windows is CR+LF and Linus is only one of those. Anyway, if you go from Windows -> Linux, the text will look okay, but will contain invisible hard line breaks. You might have to run a test build to find all of them.


Switch Notepad to no text wrapping, and then copy text.

Code blocks

Mark code blocks for syntax highlighting (using the Pygments add-in).

.. code-block:: xxx

Where xxx is the name of the Pygments lexor for that kind of code.

Each line of the code block must be indented with three spaces

For example, this is how you indicate a code block for HTML

{  // indent at least two spaces
  code block;

I use the “bro” lexor for REST code. “bro” is actually designed for some other kind of code, but I use it since there isn’t one that gives me pretty looking REST code.

.. code-block:: http
.. code-block:: json

The ‘include’ Directive

To include a block of text from an external file, use the ‘include’ directive:

.. include:: inclusion.txt

I think the inclusion file has to be .txt; .rst did not work

Section structure

lines can be made with the following characters:

= - ` : ' " ~ ^ _ * + # < >
I like to use

Topic Title (only one per source content file): # Heading 1: * Heading 2: = Heading 3: - Heading 4: ^ Heading 5: “

Sphinx Project Config Files

Sphinx Roles


The Sphinx templates



This software is required to create the PDF version of doc from LaTeX files in Sphinx.

Home Page


Download Page


Click the drop-down arrow to show the “Other” downloads.