Configuration

Authors:

Brad Stancel

Created:

04/01/2020

Modified:

09/19/2025

Configuration Overview

Check out the configuration in the Sphinx snippets section here

Remove Blank Pages from Sphinx PDF

latex_elements = {
    'extraclassoptions': 'openany,oneside'
}

Extensions

Here is a link showing the built-in extension for Sphinx.

Here are some key Sphinx extensions:

Example Configuration

Here is a real conf.py file from one of my documentation repos. This is a good starting point to copy and paste from and then just change / add / remove any needed items or text.

# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

project = 'AI Documentation'
copyright = '2025, Brad Stancel'
author = 'Brad Stancel'
release = '1.0.0'

html_favicon = '_static/_images/favicon.ico'
html_show_sourcelink = False

# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

extensions = [
    'sphinx_rtd_theme',
    'sphinxcontrib.youtube',
    'recommonmark',
    'sphinx.ext.extlinks',
    'sphinx.ext.graphviz',
    'sphinx.ext.intersphinx',
    'sphinxcontrib.plantuml',
    'sphinxcontrib.mermaid',
    'sphinx_copybutton'
]

intersphinx_mapping = {
    'linux': ('https://writings.bradstancel.com/linux-docs', None),
    'server-programs': ('https://writings.bradstancel.com/server-programs', None)
}
# We recommend adding the following config value.
# Sphinx defaults to automatically resolve *unresolved* labels using all your Intersphinx mappings.
# This behavior has unintended side-effects, namely that documentations local references can
# suddenly resolve to an external location.
# See also:
# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#confval-intersphinx_disabled_reftypes
intersphinx_disabled_reftypes = ["*"]

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = []


# -- Options for HTML output -------------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
html_theme = 'sphinx_rtd_theme'

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']

#Brad Edit - Adding a custom CSS file to see if I can get colored text in CSV Tables
html_css_files = [
'_css/sphinx-custom.css'
]


# Brad Edit - Put any links here that you want to be able to reference throughout the site
# extlinks = {
# }

# Brad Edit - Remove blank pages when creating PDF's with 'make latexpdf' - huge timesaver
latex_elements = {
'extraclassoptions': 'openany,oneside'
}