1.1. Setting up a Sphinx Auto-Doc Server

1.1.1. Initial Setup

Firstly you’ll need to install the Python pre-requisites and create the venv (virtual environment).

$ apt install python3 python3-pip python3-venv python3-virtualenv
$ mkdir sphinx
$ cd sphinx
$ virtualenv -p python3 .

Tip

If you’re not going to use the PyData Theme for Sphinx, you don’t need to install it, but I highly recommend it!

The Book and Read The Docs Themes are good alternatives.

Now activate your virtual environment and install the Sphinx addons you want to use. My recommended are the following:

$ source bin/activate
$ pip3 install sphinx
$ pip3 install sphinx-copybutton # This is a pretty good extension

# THEMES TO INSTALL - INSTALL RTD IF AUTHOR BUG IS PRESENT
## READ THE DOCS THEME
$ pip3 install sphinx-rtd-theme
## BOOK THEME
$ pip3 install sphinx-book-theme
## PYDATA THEME (THE ONE THIS PAGE USES)
$ pip3 install pydata-sphinx-theme

Once that is done you can proceed to create your own Sphinx Documentation site.

Generally you’ll want to sub-divide into folders for organization purposes, but before getting into that lets generate the project folder.

Go to the working dir you’d like to do this in and input the following commands

$ sphinx-quickstart

Usually you’re fine by just using the defaults, I’ve enabled some extensions for this Sphinx site, however you can adjust it to whatever you need.

Note

Don’t forget to change the project folder absolute path in the conf.py file

Now we can adjust the config file for Sphinx

# Uncomment the lines below

import os
import sys
# sys.path.insert(0, os.path.abspath('/opt/sphinx'))

# TODAY Format
today_fmt = '%Y/%m/%d - %H:%M'

# You might also want to add this extension to give the site nice appearance, or search for another to your liking on the Sphinx Themes Site

extensions = [
"sphinx_copybutton",
"pydata_sphinx_theme",  # Disable if not used
"sphinx_rtd_theme",     # Disable if not used
"sphinx_book_theme",    # Disable if not used
]

Tip

If you wish to print out the latest update on an RST File use |today| on the rst file

I also added .md files to the read-able source suffix section

source_suffix = ['.rst', '.md']

Once this is all done you can do the following to test the build

# Manual Build Command
$ sphinx-build -b html source/ build/

# Using Sphinx Quickstart's Makefile
$ make html

The site should be built in the build/html subdirectory.

Tip

You can make a symbolic link to avoid having to copy the site to Apache/NGINX all the time.

$ ln -s /opt/sphinx/build /var/www/sphinx

Tip

You might want to delete all the files in your build folder whenever you rebuild the site, as it might not correctly re-index the tocs.

1.1.3. Configuring the Read The Docs Theme

Add the following code block to your conf.py file:

html_theme_options = {
    # ----------------- RTD THEME
    'logo_only': True,
    'display_version': True,
    'prev_next_buttons_location': 'both',
    'collapse_navigation': False,
    'titles_only': False,
}

1.1.4. Configuring the PyData Theme

To configure the PyData Theme you’ll need to make a few changes to the following files:
  • conf.py (In your sources dir or the project’s root dir)

  • gettext.py (In the project relative path lib/python3.x/site-packages/sphinx/builders/gettext.py)

In your conf.py file add:

Warning

Don’t forget to change the 3.x to your Project’s Python Version!

# Add any paths that contain templates here, relative to this directory.
templates_path = [
    'lib/python3.x/site-packages/sphinx_book_theme/_templates',
    'lib/python3.x/site-packages/pydata_sphinx_theme/_templates',
    '_templates',
]

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
        "sphinx_copybutton",
        "pydata_sphinx_theme",
        "sphinx_rtd_theme",
        "sphinx_book_theme",
]

html_theme_options = {
    'logo_link': '',
    # ----------------- PYDATA THEME
    "use_edit_page_button": False,
    'collapse_navigation': False, # This is for PyData Theme
    'show_prev_next': False,
    "icon_links": [
        # {
        #     "name": "GitLab",
        #     "url": "",
        #     "icon": "fab fa-gitlab",
        # },
        {
            "name": "PyData Sphinx Theme",
            "url": "https://pydata-sphinx-theme.readthedocs.io/",
            "icon": "fas fa-brush",
        },
        {
            "name": "Twitter",
            "url": "",
            "icon": "fab fa-twitter-square",
        }
    ],
    "external_links": [
        {"name": "Your Website", "url": "https://localhost"}
    ]
}

And in your gettext.py file, search for the class GettextRenderer(SphinxRenderer) and add:

def escape(s: str) -> str:
    #### This conditional is being added ####
    if s is None:
        return ""
    #########################################
    s = s.replace('\\', r'\\')
    s = s.replace('"', r'\"')
    return s.replace('\n', '\\n"\n"')

1.1.5. Adding Custom CSS Files

Add the following code block to your conf.py:

html_css_files = [
    'css/style.css',
    'css/fonts.css'
]