getting started

A sphinx installation provides you with two command-line tools:

sphinx-quickstart

initiate a sphinx project:

sphinx-build

build the documentation (to html or pdf) from rst

sphinx-quickstart

At the command-line, type:

$ sphinx-quickstart

for an interactive program which queries setup options and writes out a file conf.py in the root directory of your project. Edit this file by hand afterwards to change configuration as you prefer.

I suggest accepting default locations.

Filenames referenced throughout the documentation are either relative to the current file (e.g. subdirectory/filename, ../../filename), or relative to this root directory (/root/subdirectory/../filename)

You can elect to have sphinx install a Makefile (linux) or make.bat (MS) which provides common invocations of sphinx-build.

Extensions are offered in this setup - you can elect to include these now, or do so later [1] :

• autodoc - to pull in docstrings from code
• intersphinx - to link with other python documentation
• pngmath or jsmath - to enable latex math-mode in html

sphinx-build

$ man sphinx_build

shows sphinx-build usage.

$ sphinx-build  -b html -d build/doctrees source build/html

$ sphinx-build  -b latex -d build/doctrees source build/latex

$ sphinx-build  -b doctest -d build/doctrees source

or use the convenience of make and the Makefile written by sphinx-quickstart:

$ make help                      (to see all possibilities)
$ make html                      (to render docs as html)
Build finished. The HTML pages are in build/html.

$ browse build/html/index.html   (to view the html-docs)

$ make latex                     (to render docs as tex)
$ cd build/latex
$ make all-pdf                   (to process tex file to pdf)

for the pdf, or

$ make doctest

to run doctest on the docstrings of your documented code.

In addition, you’ll see from the make help that you can also run:

$ make linkcheck

to have sphinx check all the links in your documents.

Footnote

[1]	by editing the extensions variable in the file conf.py

root-directory

location of the file conf.py from the sphinx-quickstart output.