Setting up a Sphinx Auto-Doc Server

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 .

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

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'

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

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.

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

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.

Adding a Logo

To add a Logo to your Sphinx Project (if the theme supports it) add the following line to your conf.py file:

# THEME LOGO
html_logo = 'logo.svg'

Then add your logo to the _static folder in the Sources or Root directory.

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,
}

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:

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

You can also create a for loop with the supported Python Versions to append the path for every one of them.

# Python versions supported to build paths.
supported_python_versions = ["3.6","3.7","3.8","3.9"]

# Add any paths that contain templates here, relative to this directory.
templates_path = []
templates_path += [f'lib/python{v}/site-packages/sphinx_book_theme/_templates' for v in supported_python_versions]
templates_path += [f'lib/python{v}/site-packages/pydata_sphinx_theme/_templates' for v in supported_python_versions]
templates_path.append("_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"')

Adding Custom CSS Files

Add the following code block to your conf.py:

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

Last modified at Jun 9, 2023

Setting up a Sphinx Auto-Doc Server

Initial Setup #

Adding a Logo #

Configuring the Read The Docs Theme #

Configuring the PyData Theme #

Adding Custom CSS Files #

Initial Setup

Adding a Logo

Configuring the Read The Docs Theme

Configuring the PyData Theme

Adding Custom CSS Files