Add Sphinx extensions#

The Sphinx configuration (doc/source/conf.py) file contains an extensions variable that specifies the list of extensions that are configured for use by Sphinx when generating documentation. When the Ansys templates tool is used to create a PyAnsys project from the pyansys or pyansys-advanced template, the extensions variable lists these extensions by default:

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

Extensions with names beginning with sphinx_ext are native (built-in) and are available for Sphinx’s use without any additional installation. Extensions with names that do not begin with sphinx_ext are external extensions and require installation. If a non-native extension is not installed but added to the conf.py file in the doc/source directory, attempts to build the documentation fail because Sphinx cannot find the needed extension.

Add a native extension#

To use the special features provided by a native Sphinx extension, you only need to add the extension to the extensions variable in the project’s conf.py file.

For example, the native sphinx.ext.todo extension was added to the extensions variable in the conf.py file for this guide. This extension supports use of the todo directive to create a specially formatted block of text for a task that must still be done. The blocks for todo directives do not render in the documentation by default. However, to render them in the documentation, you can add a todo_include_todos variable to the conf.py file and then set this variable to True.

Add an external extension#

To use the special features provided by an external Sphinx extension is a bit more complicated. You must install the extension in your development environment and then add it to both the project’s conf.py and its list of documentation requirements.

For example, to use cards and tab sets in your documentation, you must install and configure the external sphinx-design extension for use:

  1. If the Ansys Python Manager and Administrator window are not still open, open them.

  2. From the Administrator window’s command prompt, run the command for installing the external extension in your development environment:

    python -m pip install <external-extension-name>

    Examples follow for some of the external extensions mentioned in this documentation.

    • To install the external sphinx-design extension, run this command:

      python -m pip install sphinx-design

    • To install the external sphinx_toolbox.collapse extension, run this command:

      python -m pip install sphinx_toolbox.collapse

  3. Add the external extension to the extensions variable in your project’s conf.py file.

  4. Add the external extension to your project’s documentation requirements as indicated in the next topic.

Add the extension to the documentation requirements#

Documentation requirements list the pip packages that Sphinx requires for building the documentation. Depending on the project’s configuration, you list these packages in either the pyproject.toml file or the requirements_doc_txt file.

The pyproject.toml file#

Most projects specify documentation requirements in a pyproject.toml file, which resides in the root folder. In this file, the doc variable defines the required pip packages and their versions like this.

doc = [
    "ansys-sphinx-theme==0.12.3",
    "docker==6.1.3",
    "ipyvtklink==0.2.3",
    "jupyter_sphinx==0.4.0",
    "jupytext==1.15.2",
    "myst-parser==2.0.0",
    "nbconvert==7.9.2",
    "nbsphinx==0.9.3",
    "notebook==7.0.5",
    "numpydoc==1.6.0",
    "panel==1.2.3",
    "pyvista[trame]==0.41.1",
    "requests==2.31.0",
    "sphinx==7.2.5",
    "sphinx-autoapi==3.0.0",
    "sphinx-autodoc-typehints==1.24.0",
    "sphinx-copybutton==0.5.2",
    "sphinx_design==0.5.0",
    "sphinx-jinja==2.0.2",
    "vtk==9.2.6",
]

The requirements_doc_txt file#

Some projects specify documentation requirements in a requirements_doc_txt file. The root folder of such a project typically has a requirements directory that contains this TXT file, which defines the required pip packages and their versions like this:

Sphinx==7.1.2
jupyter_sphinx==0.4.0
numpydoc==1.5.0
matplotlib==3.7.2
ansys-sphinx-theme==0.10.2
pypandoc==1.11
pytest-sphinx==0.5.0
sphinx-autobuild==2021.3.14
sphinx-autodoc-typehints==1.24.0
sphinx-copybutton==0.5.2
sphinx-gallery==0.13.0
sphinx-notfound-page==0.8.3
sphinxcontrib-websupport==1.2.5
sphinxemoji==0.2.0
autodocsumm==0.2.11

Learn more about extensions#

As you can see, PyAnsys projects add many extensions to their conf.py files and documentation requirements. Here are some other native and non-native extensions that you might see:

  • sphinx.ext.coverage

  • sphinx.ext.doctest

  • sphinx.ext.extlinks

  • sphinx.ext.graphviz

  • sphinx.ext.napoleon

  • sphinx.ext.viewcode

  • sphinx_toolbox.collapse

For more information on extensions, see Extensions in the Sphinx documentation. In addition to the external (third-party) extensions collected in the sphinx-contrib organization, you can search the internet to find other Sphinx extensions or learn more about the ones in the preceding list.