RST Workshop: Setting up a Sphinx Server

Note

This guide serves two purposes:

1. It is the result of part 1, RST Workshop: Overview.

2. It serves as a basic guide to configuring Sphinx on a server.

Table of Contents

• RST Workshop: Setting up a Sphinx Server

  • Overview

  • Installing Sphinx

    • Spin up a VPS with your favorite Linux distro

    • Install Sphinx using the package manager

  • Configure Sphinx using sphinx-quickstart

  • Rendering to HTML

  • Adding Content

    • Default index.html

    • Create Folders

  • Install a Different Theme

    • Install Read the Docs Theme

Overview

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.

Installing Sphinx

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 apt and pip3.

Note

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.

Caution

Installing both versions could result in a conflict.

1. Update your repository and upgrade any out-of-date packages using apt-get update && apt upgrade.

2. Install a version of Sphinx:

   • Sphinx version 1.x

     1. Install Sphinx version 1: apt-get -y install python3-sphinx

   • Sphinx version 2.x

     1. Install pip3: apt-get -y install python3-pip

     2. Install Sphinx version 2: pip3 install Sphinx

Configure Sphinx using sphinx-quickstart

You need to configure Sphinx the first time you use it. Sphinx provides a quickstart tool!

Important

Create and then change to the directory of your Sphinx code and RST content. The default installation directory is ./, which is the current directory.

1. Create a project folder, then navigate to that folder

   • For example: mkdir -p /opt/sphinx && cd /opt/sphinx

2. Execute command sphinx-quickstart

3. 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.

   Output of ‘sphinx-quickstart’ for v.1

   > Separate source and build directories (y/n) [n]:
   
   Inside the root directory, two more directories will be created; "_templates"
   for custom HTML templates and "_static" for custom stylesheets and other static
   files. You can enter another prefix (such as ".") to replace the underscore.
   > Name prefix for templates and static dir [_]:
   
   The project name will occur in several places in the built documentation.
   > Project name: Conference Demo
   > Author name(s): BilimEdtech
   > Project release []:
   
   If the documents are to be written in a language other than English,
   you can select a language here by its language code. Sphinx will then
   translate text that it generates into that language.
   
   For a list of supported codes, see
   http://sphinx-doc.org/config.html#confval-language.
   > Project language [en]:
   
   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]:
   
   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]:
   Indicate which of the following Sphinx extensions should be enabled:
   > autodoc: automatically insert docstrings from modules (y/n) [n]:
   > doctest: automatically test code snippets in doctest blocks (y/n) [n]:
   > intersphinx: link between Sphinx documentation of different projects (y/n) [n]:
   > todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: y
   > coverage: checks for documentation coverage (y/n) [n]:
   > imgmath: include math, rendered as PNG or SVG images (y/n) [n]:
   > mathjax: include math, rendered in the browser by MathJax (y/n) [n]:
   > ifconfig: conditional inclusion of content based on config values (y/n) [n]:
   > viewcode: include links to the source code of documented Python objects (y/n) [n]: y
   > githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]:
   
   A Makefile and a Windows command file can be generated for you so that you
   only have to run e.g. `make html` instead of invoking sphinx-build
   directly.
   > Create Makefile? (y/n) [y]:
   > Create Windows command file? (y/n) [y]: n
   

Note

• The configurations for your Sphinx project are in file conf.py.

• Delete file conf.py to 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.

1. Build the HTML by executing command make html

   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.
   

2. Navigate to the URL of the Sphinx instance to view rendered HTML.

   

Adding Content

Note

All of the RST contents and settings are in the root of the Sphinx directory.

Default index.html

Executing make html on a default project creates an index.html in the root folder of the project using the parameters from conf.py.

Default ‘index.rst’ file

.. 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`

Create Folders

Sphinx makes it easy to organize content in folders.

1. Create a folder, such as web-guide.

2. Create a file web-guide/index.rst with the following content:

   web-guide/index.rst contents

   *******************
   Project X Web Guide
   *******************
   
   This guide provides the documentation for our web frontend.
   

3. Now, link to the web-guide/index.rst by placing the path in the root index.rst.

   ./index.rst contents

   .. 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:
   
      web-guide/index
   
   
       . . .
   

4. 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:

   Running Sphinx v2.3.1
   loading pickled environment... 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: 0 added, 1 changed, 0 removed
   reading sources... [100%] index
   /opt/sphinx/index.rst:9: WARNING: toctree contains reference to
       nonexisting document ' web-guide/index'
   looking for now-outdated files... none found
   pickling environment... done
   checking consistency... /opt/sphinx/web-guide/index.rst:
       WARNING: document isn’t included in any toctree
   done
   preparing documents... done
   writing output... [100%] index
   generating indices...  genindexdone
   done
   copying static files... ... done
   copying extra files... done
   dumping search index in English (code: en)... done
   dumping object inventory... done
   build succeeded, 2 warnings.
   
   The 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.

• Read the Docs Theme

• Alabaster

• Sphinx Bootstrap Theme

• Guzzle Theme

Install Read the Docs Theme

Read the Docs Theme is a popular theme for Sphinx. PyPI hosts Read the Docs theme.

1. Install pip3 if you do not install it earlier: apt-get -y install python3-pip

2. Install sphinx-rtd-theme using pip3: pip3 install sphinx-rtd-theme

3. Edit your conf.py file and make the following modifications:

   conf.py

   import sphinx_rtd_theme
   
   extensions = [
       ...
       'sphinx_rtd_theme',
   ]
   
   # html_theme = 'alabaster'
   html_theme = "sphinx_rtd_theme"
   

4. Rebuild the HTML to display the new theme. You can rebuild the HTML in the container from the host using docker exec.

   # 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"
   

   

Hint

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 _build and then use make html` to generate a fresh copy.

From the host

rm -r sphinx/_build/html
docker-compose exec sphinx bash -c "cd /opt/sphinx && make html"