RST Workshop: Setting up a Sphinx Server
This guide serves two purposes:
It is the result of part 1, RST Workshop: Overview.
It serves as a basic guide to configuring Sphinx on a server.
Table of Contents
Sphinx is a platform that renders RST files to a web application that is suitable for documentation. This guide provides a quick installation guide for someone wanting to set up Sphinx on a VSP.
The install sphinx guide provides a good starting point, but we will make other changes to install the latest version of Sphinx from PyPI.
The VPS setup for this workshop uses Docker image nginx:latest, which uses Debian 10.
The Sphinx documentation
provides instructions for Debian/Ubuntu (apt), RHEL/CentOS (yum),
and MacOS (homebrew). This guide will uses the
apt package manager..
Unfortunately, the apt package manager for Debian has an old version of
Sphinx (Sphinx 1.8.4). It works, but PyPI has the latest version of
Sphinx. Therefore, this guide
shows to install Sphinx using both
Other distributions are supported using pip, such as Alpine Linux. However, additional knowledge is required to install prerequisites for specific Python packages.
Spin up a VPS with your favorite Linux distro
This workshop uses a simple
docker-compose.yml file to start the
instance and then uses Nginx on the host as a reverse proxy. You can view
the RST Workshop: Docker Environment.
Install Sphinx using the package manager
You can choose to install the Sphinx version (1.7.x) using the apt package manager or you install the latest version (2.x) using from PyPI using.
Installing both versions could result in a conflict.
Update your repository and upgrade any out-of-date packages using
apt-get update && apt upgrade.
Install a version of Sphinx:
Sphinx version 1.x
Install Sphinx version 1:
apt-get -y install python3-sphinx
Sphinx version 2.x
apt-get -y install python3-pip
Install Sphinx version 2:
pip3 install Sphinx
Configure Sphinx using
You need to configure Sphinx the first time you use it. Sphinx provides a quickstart tool!
Create and then change to the directory of your Sphinx
code and RST content. The default installation directory is
which is the current directory.
Create a project folder, then navigate to that folder
mkdir -p /opt/sphinx && cd /opt/sphinx
Follow the prompts (from version 1.x)
We’ve highlighted the lines that we entered a value other than default. Add the extensions that you find useful.
1> Separate source and build directories (y/n) [n]: 2 3Inside the root directory, two more directories will be created; "_templates" 4for custom HTML templates and "_static" for custom stylesheets and other static 5files. You can enter another prefix (such as ".") to replace the underscore. 6> Name prefix for templates and static dir [_]: 7 8The project name will occur in several places in the built documentation. 9> Project name: Conference Demo 10> Author name(s): BilimEdtech 11> Project release : 12 13If the documents are to be written in a language other than English, 14you can select a language here by its language code. Sphinx will then 15translate text that it generates into that language. 16 17For a list of supported codes, see 18http://sphinx-doc.org/config.html#confval-language. 19> Project language [en]: 20 21The file name suffix for source files. Commonly, this is either ".txt" 22or ".rst". Only files with this suffix are considered documents. 23> Source file suffix [.rst]: 24 25One document is special in that it is considered the top node of the 26"contents tree", that is, it is the root of the hierarchical structure 27of the documents. Normally, this is "index", but if your "index" 28document is a custom template, you can also set this to another filename. 29> Name of your master document (without suffix) [index]: 30Indicate which of the following Sphinx extensions should be enabled: 31> autodoc: automatically insert docstrings from modules (y/n) [n]: 32> doctest: automatically test code snippets in doctest blocks (y/n) [n]: 33> intersphinx: link between Sphinx documentation of different projects (y/n) [n]: 34> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: y 35> coverage: checks for documentation coverage (y/n) [n]: 36> imgmath: include math, rendered as PNG or SVG images (y/n) [n]: 37> mathjax: include math, rendered in the browser by MathJax (y/n) [n]: 38> ifconfig: conditional inclusion of content based on config values (y/n) [n]: 39> viewcode: include links to the source code of documented Python objects (y/n) [n]: y 40> githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]: 41 42A Makefile and a Windows command file can be generated for you so that you 43only have to run e.g. `make html` instead of invoking sphinx-build 44directly. 45> Create Makefile? (y/n) [y]: 46> Create Windows command file? (y/n) [y]: n
The configurations for your Sphinx project are in file
conf.pyto run the quickstart again.
Rendering to HTML
We can configure Sphinx to auto-build the output when it detects a change, or we can initiate a manual build.
The command to generate output is
make <output>. Sphinx can convert RST
to various formats. You can run the
make command without any args to
view the possible output types.
root@26f88a20b58c:/opt/sphinx# make Sphinx v2.3.1 Please use `make target` where target is one of html to make standalone HTML files dirhtml to make HTML files named index.html in directories singlehtml to make a single large HTML file pickle to make pickle files json to make JSON files htmlhelp to make HTML files and an HTML help project qthelp to make HTML files and a qthelp project devhelp to make HTML files and a Devhelp project epub to make an epub latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter latexpdf to make LaTeX and PDF files (default pdflatex) latexpdfja to make LaTeX files and run them through platex/dvipdfmx text to make text files man to make manual pages texinfo to make Texinfo files info to make Texinfo files and run them through makeinfo gettext to make PO message catalogs changes to make an overview of all changed/added/deprecated items xml to make Docutils-native XML files pseudoxml to make pseudoxml-XML files for display purposes linkcheck to check all external links for integrity doctest to run all doctests embedded in the documentation (if enabled) coverage to run coverage check of the documentation (if enabled)
Our desired output is HTML.
Build the HTML by executing command
root@1a40c1841674:/opt/sphinx# make html Running Sphinx v2.3.1 making output directory... done 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.
Navigate to the URL of the Sphinx instance to view rendered HTML.
All of the RST contents and settings are in the root of the Sphinx directory.
make html on a default project creates an
in the root folder of the project using the parameters from
.. Demo documentation master file, created by sphinx-quickstart on Sun Dec 29 06:49:53 2019. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. Welcome to Demo's documentation! ================================ .. toctree:: :maxdepth: 2 :caption: Contents: Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search`
Sphinx makes it easy to organize content in folders.
Create a folder, such as
Create a file
web-guide/index.rstwith the following content:
******************* Project X Web Guide ******************* This guide provides the documentation for our web frontend.
Now, link to the
web-guide/index.rstby placing the path in the root
1.. Demo documentation master file, created by 2 sphinx-quickstart on Sun Dec 29 06:49:53 2019. 3 You can adapt this file completely to your liking, but it should at least 4 contain the root `toctree` directive. 5 6Welcome to Demo's documentation! 7================================ 8 9.. toctree:: 10 :maxdepth: 2 11 :caption: Contents: 12 13 web-guide/index 14 15 16 . . .
Build the HTML and then refresh the page. The page should show up in the left navigation panel and on the home page.
Pay close attention to the number of spaces, which should be exactly three.
A wrong indentation level will result in an error similar to:
1Running Sphinx v2.3.1 2loading pickled environment... done 3building [mo]: targets for 0 po files that are out of date 4building [html]: targets for 1 source files that are out of date 5updating environment: 0 added, 1 changed, 0 removed 6reading sources... [100%] index 7/opt/sphinx/index.rst:9: WARNING: toctree contains reference to 8 nonexisting document ' web-guide/index' 9looking for now-outdated files... none found 10pickling environment... done 11checking consistency... /opt/sphinx/web-guide/index.rst: 12 WARNING: document isn’t included in any toctree 13done 14preparing documents... done 15writing output... [100%] index 16generating indices... genindexdone 17done 18copying static files... ... done 19copying extra files... done 20dumping search index in English (code: en)... done 21dumping object inventory... done 22build succeeded, 2 warnings. 23 24The HTML pages are in _build/html.
Install a Different Theme
Sphinx generates HTML, CSS, JS and support code using the Alabaster theme by default. Sphinx has ample support for themes. Write the Docs recommends these top four themes.
Install Read the Docs Theme
Read the Docs Theme is a popular theme for Sphinx. PyPI hosts Read the Docs theme.
pip3if you do not install it earlier:
apt-get -y install python3-pip
pip3 install sphinx-rtd-theme
conf.pyfile and make the following modifications:
import sphinx_rtd_theme extensions = [ ... 'sphinx_rtd_theme', ] # html_theme = 'alabaster' html_theme = "sphinx_rtd_theme"
Rebuild the HTML to display the new theme. You can rebuild the HTML in the container from the host using
# Using docker-compose docker-compose exec sphinx bash -c "cd /opt/sphinx && make html" # Using docker docker exec -t sphinx_nginx bash -c "cd /opt/sphinx && make html"
Sometimes the HTML in folder
_build contains old data,
especially if you remove or rename a file.
To solve this problem, you can safely delete the
and then use
make html` to generate a fresh copy.
rm -r sphinx/_build/html docker-compose exec sphinx bash -c "cd /opt/sphinx && make html"