Required Sphinx configuration#

The following 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 in this topic, 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 flags: -j, -W, and --keep-going.

The -j flag 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.
The -W flag turns warnings into errors. This guarantees that documentation health is maximized.
The --keep-going flag specifies whether to render the whole documentation, even if a warning is found. This flag 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`#