Required Sphinx configuration#

This page explains the minimum required Sphinx configuration for building the documentation of a PyAnsys library.

When installing Sphinx, a program named sphinx-build also gets installed. This program is in charge of collecting, parsing, and rendering all ReStructuredText (RST) files in The doc directory.

The behavior of the sphinx-build program is controlled through either a Makefile (for POSIX systems) or a make.bat file (for Windows systems). Once the sphinx-build command is triggered, the configuration declared in the conf.py file is applied when rendering the documentation pages.

The `conf.py` file#

The following conf.py file provides the minimum required configuration for a PyAnsys library. To guarantee consistency across PyAnsys libraries, you should only make custom additions on top of this configuration.

"""Sphinx documentation configuration file."""

from datetime import datetime

from ansys_sphinx_theme import pyansys_logo_black as logo

# Project information
project = "ansys-product-library"
copyright = f"(c) {datetime.now().year} ANSYS, Inc. All rights reserved"
author = "ANSYS, Inc."
release = version = "0.1.dev0"

# Select desired logo, theme, and declare the html title
html_logo = logo
html_theme = "ansys_sphinx_theme"
html_short_title = html_title = "pyproduct-library"

# specify the location of your github repo
html_theme_options = {
    "github_url": "https://github.com/ansys/pyproduct-library",
    "show_prev_next": False,
    "show_breadcrumbs": True,
    "additional_breadcrumbs": [
        ("PyAnsys", "https://docs.pyansys.com/"),
    ],
}

# Sphinx extensions
extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.autosummary",
    "sphinx.ext.autosectionlabel",
    "numpydoc",
    "sphinx.ext.intersphinx",
    "sphinx_copybutton",
]

# Intersphinx mapping
intersphinx_mapping = {
    "python": ("https://docs.python.org/dev", None),
    # kept here as an example
    # "scipy": ("https://docs.scipy.org/doc/scipy/reference", None),
    # "numpy": ("https://numpy.org/devdocs", None),
    # "matplotlib": ("https://matplotlib.org/stable", None),
    # "pandas": ("https://pandas.pydata.org/pandas-docs/stable", None),
    # "pyvista": ("https://docs.pyvista.org/", None),
    # "grpc": ("https://grpc.github.io/grpc/python/", None),
}

# numpydoc configuration
numpydoc_show_class_members = False
numpydoc_xref_param_type = True

# Consider enabling numpydoc validation. See:
# https://numpydoc.readthedocs.io/en/latest/validation.html#
numpydoc_validate = True
numpydoc_validation_checks = {
    "GL06",  # Found unknown section
    "GL07",  # Sections are in the wrong order.
    "GL08",  # The object does not have a docstring
    "GL09",  # Deprecation warning should precede extended summary
    "GL10",  # reST directives {directives} must be followed by two colons
    "SS01",  # No summary found
    "SS02",  # Summary does not start with a capital letter
    "SS03",  # Summary does not end with a period
    "SS04",  # Summary contains heading whitespaces
    "SS05",  # Summary must start with infinitive verb, not third person
    "RT02",  # The first line of the Returns section should contain only the
    # type, unless multiple values are being returned"
}


# static path
html_static_path = ["_static"]

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

# The suffix(es) of source filenames.
source_suffix = ".rst"

# The master toctree document.
master_doc = "index"

# Generate section labels up to four levels deep
autosectionlabel_maxdepth = 4

Automation files#

As indicated earlier on this page, the sphinx-build program and all its options and arguments can be automated by using a Makefile file or a make.bat file. These files should be placed at the first level of the doc directory, next to the source directory.

Notice that both files contain a SPHINXOPTS variable with these options: -j, -W, and --keep-going.

-j: Indicates the number of jobs (number of cores) to use. The default value is auto, which means that the number of cores in the CPU is to be automatically detected.
-W: turns warnings into errors. This guarantees that documentation health is maximized.
--keep-going: Specifies whether to render the whole documentation, even if a warning is found. This option enables developers to be aware of the full set of warnings.

A special rule named pdf is also included. This rule is in charge of generating a PDF file for the library’s documentation.

Example for `Makefile`#

The following code collects the required options and automation rules for the Makefile program to use when building documentation for a PyAnsys library:

# Minimal makefile for Sphinx documentation

# You can set these variables from the command line:
SPHINXOPTS    = -j auto -W --keep-going
SPHINXBUILD   = sphinx-build
SOURCEDIR     = source
BUILDDIR      = build

# Put the "help" rule the first one so that "make" without argument behaves like "make help".
help:
	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

.PHONY: help Makefile

# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
	
# Clean build directory files
clean:
	rm -rf build
	find . -type d -name "_autosummary" -exec rm -rf {} +

# Build PDF documentation
pdf:
	@$(SPHINXBUILD) -M latex "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
	cd build/latex && latexmk -r latexmkrc -pdf *.tex -interaction=nonstopmode || true
	(test -f build/latex/*.pdf && echo pdf exists) || exit 1

Example for `make.bat`#

The following code collects the required options and automation rules for the make.bat program to use when building documentation for a PyAnsys project:

@ECHO OFF

pushd %~dp0

REM Command file for Sphinx documentation

if "%SPHINXBUILD%" == "" (
	set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=source
set BUILDDIR=build
set SPHINXOPTS=-j auto -W --keep-going

if "%1" == "" goto help
if "%1" == "clean" goto clean
if "%1" == "pdf" goto pdf

%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
	echo.
	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
	echo.installed, then set the SPHINXBUILD environment variable to point
	echo.to the full path of the 'sphinx-build' executable. Alternatively you
	echo.may add the Sphinx directory to PATH.
	echo.
	echo.If you don't have Sphinx installed, grab it from
	echo.http://sphinx-doc.org/
	exit /b 1
)

%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
goto end

:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%

:clean
rmdir /s /q %BUILDDIR% > /NUL 2>&1 
for /d /r %SOURCEDIR% %%d in (_autosummary) do @if exist "%%d" rmdir /s /q "%%d"
goto end

:pdf
	%SPHINXBUILD% -M latex %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
	cd "%BUILDDIR%\latex"
	for %%f in (*.tex) do (
	pdflatex "%%f" --interaction=nonstopmode)
	
:end
popd

Required Sphinx configuration#

The conf.py file#

Automation files#

Example for Makefile#

Example for make.bat#

The `conf.py` file#

Example for `Makefile`#

Example for `make.bat`#