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
%USERPROFILE%\\python_telesign_sdk\\doc\\
Working Directory¶
The Working directory is one level up from the Source directory.
E.g.,
C:\Users\Chris\src\python_rest_api\doc\user\v1\
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¶
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.
Note
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
Make¶
GNU Make is a program that simplifies the building process.
Install Make¶
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.
Run the Installer as Administrator.
Create a new environment variable
MAKE_HOME = C:Program Files (x86)GnuWin32
Add it to the Path
;%MAKE_HOME%;%MAKE_HOME%\bin
Reboot your computer to make the environment variables take affect.
sphinx-build¶
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. |
Modes¶
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.
C:\\Python27\\Scripts\\sphinx-build.exe
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¶
Usage
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”
Examples¶
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”
Expanded¶
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" (
%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
if errorlevel 1 exit /b 1
echo.
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
Syntax
%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
Legend
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).
- ALLSPHINXOPTS = -d %BUILDDIR%/doctrees %SPHINXOPTS%
- = -d _build/doctrees %SPHINXOPTS%
Example
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
Note
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)
set SPHINXOPTS=-E
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.
- Open a command prompt. You can use the Git BASH.
- Change to the SDK directory (\python_telesign_sdk\).
- Reinstall the SDK
python setup.py install
- Rebuild the docs
python setup.py doc
reST Reference¶
Directives¶
.. rubric::
In this Section
toctree¶
.. toctree::
:maxdepth: 2
:numbered:
:titlesonly:
:glob:
:hidden:
Hyperlinking¶
http://sphinx-doc.org/markup/inline.html?highlight=hyperlink
To another topic in the same doc set¶
:ref:`xref-topic-file`
Example¶
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
file:///%USERPROFILE%/src/python_rest_api/doc/user/v1/build/html/content/verify-2way-sms.html#xref-verify-2way-sms-resource-uri-object
You Provide Your Own Link Text¶
:ref:`Link title <label-name>`
:ref:`reference <xref-verify-2way-sms-reference_id-object>`
Example¶
The phone number must include its associated :ref:`country code <xref-country-codes>` (1 for North America).
To a Web URL¶
`Link text <http://example.com>`_
Admonitions¶
".. attention::", ".. caution::", ".. danger::", ".. error::", ".. hint::", ".. important::", ".. note::", ".. tip::", ".. warning::".
Note: only “note” renders with nice formatting.
E.g.,
Note
You must base64 decode it to use in generating the signature.
Tip
You can get the results automatically by subscribing for a transaction callback.
Tags¶
.. 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'
else:
# some
Building an HTML File From an rst File¶
Run the rst2html Python script on the rst file.
- Open a DOS Command Prompt Window.
- Navigate to the directory that contains the REst file you want to convert.
- Type rst2html.py \.rst \*.html*.
Example¶
rst2html.py Readme.rst Readme.html
Switches¶
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
C:\\Users\\Chris\\python_telesign_sdk\\doc\\_build\\html\\The main web page is the file
%USERPROFILE%\\python_telesign_sdk\\doc\\_build\\html\\index.html
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:
C:\\Users\\Chris\\python_telesign_sdk\\doc\\_build\\1.0.4\\
Doc build directories¶
For Testing
/src/ts/python_rest_api/doc/test/
For Public User Docs
/src/ts/python_rest_api/doc/user/
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¶
Note
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'
Resources¶
RST – reStructuredText¶
http://people.ee.ethz.ch/~creller/web/tricks/reST.html
How do I convert a word document to reStructured text?¶
http://groups.google.com/group/sphinx-dev/browse_thread/thread/77b0db51eb994775?pli=1
Docutils Link List¶
http://docutils.sourceforge.net/docs/user/links.html#import
An Introduction to reStructuredText¶
http://docutils.sourceforge.net/docs/ref/rst/introduction.html
Pandoc¶
You use Pandoc to convert HTML to RST.
http://johnmacfarlane.net/pandoc/
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.
E.g.,¶
pandoc -f html -t rst -o table1.txt table1.htm
To install Pandoc¶
http://johnmacfarlane.net/pandoc/installing.html
Pandoc User’s Guide¶
http://johnmacfarlane.net/pandoc/README.html
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.
Workaround¶
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.
For HTML¶
.. code-block:: http
For JSON¶
.. 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
Hypertext Links¶
For inline web links (links to external files or websites):
`Link text <http://example.com/>`_
Sphinx Project Config Files¶
Sphinx Roles
C:\\Python27\\Lib\\site-packages\\Sphinx-1.1.3-py2.7.egg\\sphinx\\roles.py
The Sphinx templates
C:\\Python27\\Lib\\site-packages\\Sphinx-1.1.3-py2.7.egg\\sphinx\\themes\\
