Deeper look on the conf.py file

So, the custom conf.py file I recommend in Adding and using Sphinx in your project is:

conf.py

# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Path setup --------------------------------------------------------------

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.

import os
import sys
sys.path.insert(0, os.path.abspath(os.path.join('..', '..')))


# -- Project information -----------------------------------------------------

project = 'Demorepo'
copyright = '2023, Eduardo Castro'
author = 'Eduardo Castro'

# The full version, including alpha/beta/rc tags
release = '1.0'


# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
    'numpydoc',             # NumPy documentation
    'sphinx.ext.viewcode',  # Link to local code
    'myst_parser',          # For using Markdown inside reST
    'sphinx_design',        # To add buttons and cards
]

# 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 = []

# Language 
language = "en"


# -- Extension config --------------------------------------------------------

# Numpydoc
numpydoc_show_class_members = True 
numpydoc_class_members_toctree = False
numpydoc_show_inherited_class_members = False

# Autodoc
autodoc_default_options = {
    # Autodoc members
    "members": True,
    # Autodoc undocumented memebers
    "undoc-members": False, 
    # Autodoc private memebers
    "private-members": True
    }
# No document TypeHints
autodoc_typehints = "none"

# Autosummary
autosummary_generate = True
autosummary_generate_overwrite = True

# MyST
myst_heading_anchors = 4


# -- 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 = 'pydata_sphinx_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']


# -- Theme configuration -----------------------------------------------------

# Sidebar configuration
html_sidebars = {
    "**": ["search-field.html", "sidebar-nav-bs.html"],
    'index': []
    }

# General theme options
html_theme_options = {
    # Logo
    'logo': {'text': project},
    # Upper bar icons
    'navbar_end': ['theme-switcher', 'navbar-icon-links'],
    # Icon links
    "icon_links": [
        # GitHub of the proyect
        {"name": "GitHub",
         "url": "https://github.com/ecastroth/sphinx-documentation-demo",
         "icon": "fa-brands fa-square-github",
         "type": "fontawesome",}
    ]
}

As you can see, the conf.py file is a Python file that is known as the “build configuration file” and contains on most cases all the configuration needed to customize Sphinx input and output behavior.

Built-in modifications

First of all, you’ll need to say to Sphinx where the directory with your code is, relative to the conf.py file. This is done on the lines:

conf.py lines 13 to 15

import os
import sys
sys.path.insert(0, os.path.abspath(os.path.join('..', '..')))

The line 48 adds the Sphinx default texts language for the project:

conf.py lines 48 and 49

# Language 
language = "en"

Line 84 sets the theme of the documentation to be the PyData Sphinx Theme. The same one used by NumPy, Jupyter, Matplotlib, Pandas, SciPy and many other great projects -so even if your project is not that great, I asure you that your documentation will be-.

conf.py line 84

html_theme = 'pydata_sphinx_theme' 

Customizing the theme

As you can see, the conf.py file ads a section for theme customization. You can find a full description of the configuration posibilities on the User Guide.

The configuration lines regarding the configuration of the theme founded on the conf.py are divided into two main sections. Lines 94 to 97 configures the left sidebar,

conf.py lines 94 to 97

# Sidebar configuration
html_sidebars = {
    "**": ["search-field.html", "sidebar-nav-bs.html"],
    'index': []
    }

This code adds two items:

1. A search bar.

2. A bootstrap-friendly navigation section. When there are no pages to show, it dissapears.

On the other hand, lines 99 to 113 adds some little tweaks:

conf.py lines 99 to 113

# General theme options
html_theme_options = {
    # Logo
    'logo': {'text': project},
    # Upper bar icons
    'navbar_end': ['theme-switcher', 'navbar-icon-links'],
    # Icon links
    "icon_links": [
        # GitHub of the proyect
        {"name": "GitHub",
         "url": "https://github.com/ecastroth/sphinx-documentation-demo",
         "icon": "fa-brands fa-square-github",
         "type": "fontawesome",}
    ]
}

• Line 102 sets the title of the documentation (on the left upper corner). In this guide, the text logo is the same name used for the project: “Demorepo”. Note that it can also be an image.

• Line 104 adds the light/black theme color switch and a icon bar with links to the upper navigation bar.

• Lines 105 to 113 configure the icons to display on the upper right corner, as you can see, a GitHub icon is added with a link to the repository of this guide.

Extensions

As it was discussed, Sphinx make use of extensions to add some functionalities to your documentation, such as automatic use of docstrings, autosummary of objects in files or syntaxis detection of syle (such as NumpyDocs). Some of this extensions come built-in with Sphinx and others are developed by third-parties, which can be installed using pip.

Here, we’ll cover the extensions used on the conf.py file. As you can see the extensions used are listed on the lines 33 to 38:

conf.py lines 33 to 38

extensions = [
    'numpydoc',             # NumPy documentation
    'sphinx.ext.viewcode',  # Link to local code
    'myst_parser',          # For using Markdown inside reST
    'sphinx_design',        # To add buttons and cards
]

Extensions normally allow further configuration of its features, in the conf.py file, it can be found on the section from line 52 to 76:

conf.py lines 52 to 76

# -- Extension config --------------------------------------------------------

# Numpydoc
numpydoc_show_class_members = True 
numpydoc_class_members_toctree = False
numpydoc_show_inherited_class_members = False

# Autodoc
autodoc_default_options = {
    # Autodoc members
    "members": True,
    # Autodoc undocumented memebers
    "undoc-members": False, 
    # Autodoc private memebers
    "private-members": True
    }
# No document TypeHints
autodoc_typehints = "none"

# Autosummary
autosummary_generate = True
autosummary_generate_overwrite = True

# MyST
myst_heading_anchors = 4

Built-in extensions

A rule of thumb to know which extensions are built-in with sphinx, is that its names allways begin with sphinx.ext.NAME, where NAME is the name of the extension. On the config file, 3 built-in extensions are activated (The first one explicitly becouse its in the list and the other two implicitly as their activated by the use of the numpydocs extension):

See also

A full list of Sphinx built-in extensions and links to its documentations can be found here.

1. sphinx.ext.viewcode

This extension allow for the Show Source button to appear on the right sidebar. This extension does not have any extra configuration on the conf.py lines 52 to 76.

See also

You can find further information of this extension on the viewcode documentation page.

2. sphinx.ext.autosummary

This extension generates function/method/attribute summary lists or files and its especially useful when your docstrings are long and detailed, and putting each one of them on a separate page makes them easier to read.

The configuration of this extension can be found on lines 71 to 73 on conf.py lines 52 to 76:

• autosummary_generate: create .rst with a table with the objects inside files summarized. The file can be generated passing a custom template.

• autosummary_generate_overwrite:

See also

You can find further information of this extension on the autosummary documentation page.

3. sphinx.ext.autodoc

This extension import the modules you are documenting, and pull in documentation from docstrings in a automatic way.

Warning

Some common error founded when using autodoc is that the extension is unable to import the modules or packages with your code. This behavior can be disabled on the conf.py file.

The configuration of this extension can be found on lines 59 to 69 on conf.py lines 52 to 76:

• autodoc_default_options:

  The default options for autodoc directives. They are applied to all autodoc directives automatically.

• members:

  autodoc will generate document for the members of the target module, class or exception (recursively)

• undoc-members:

  autodoc will not generate document for the members not having docstings

• private-members:

  autodoc will also generate document for the private members

• autodoc_typehints:

  No typehints are shown.

See also

You can find further information of this extension on the autodoc documentation page.

Thrid-parties extensions

These are the third party extensions used on the config file:

1. numpydoc

This extension provides support for the Numpy docstring standard in Sphinx.

The configuration of this extension can be found on lines 54 to 57 on conf.py lines 52 to 76:

• numpydoc_show_class_members:

  Show all members of a class in the Methods and Attributes sections automatically.

• numpydoc_class_members_toctree

  Do not create a Sphinx table of contents for the lists of class methods and attributes.

• numpydoc_show_inherited_class_members

  Do not show all inherited members of a class in the Methods and Attributes sections automatically.

See also

You can find more information about this extension in the NumpyDocs documentation.

2. myst-parser

This extension translates Markdown files to reStructuredText files, allowing for the use of .md files into your documentation. An example of this can be found on the use of the file How to write DocStrings. Possibly you didn’t even notice, but if you see the source code you’ll see its a Markdown file!

The only configuration on the conf.py lines 52 to 76 regarding this extension is found on line 76. myst_heading_anchors is used only for Markdown header references inside file, such as [link to header](#SOME-HEADER) to work.

See also

You can find more information about this extension in the MyST Parser documentation.

3. sphinx-design

This extension adds several UI components and provide extra flexibility for content creation. These include badges, buttons, cards, and tabs, among other components.

See also

You can find more information about this extension in the Sphinx Design documentation.