Basic configuration#

To use the Ansys Sphinx Theme, add the following line to your project’s Sphinx conf.py file:

html_theme = "ansys_sphinx_theme"

The Ansys Sphinx Theme provides these features:

PyAnsys and Ansys logos#

The Ansys Sphinx Theme includes the PyAnsys and Ansys logos. All the logos are available in the ansys_sphinx_theme/static/ directory.

To use the logo in both dark and light modes, add the following code to the``html_theme_options`` dictionary in your project’s Sphinx conf.py file:

html_theme_options = {
    "logo": "ansys",
}

html_theme_options = {
    "logo": "pyansys",
}

html_theme_options = {
    "logo": "no_logo",
}

Note

By default, if ansys logo is displayed, the logo links to the Ansys website. If the PyAnsys logo is displayed, the logo links to the PyAnsys website. If you want to change the link, you can set the logo_link option in the conf.py file.

For example:

html_theme_options = {
    "logo": "ansys",
    "logo_link": "https://www.example.com",
}

Note

If you use the logo option, make sure to remove the html_logo option from the conf.py file. logo option overrides the html_logo option and display the specified logo.

You can also add a custom logo by specifying the path to the logo file as specified in pydata-sphinx-theme.

For example:

html_theme_options = {
    "logo": {
        "image_light": "_static/logo-light.png",
        "image_dark": "_static/logo-dark.png",
    }
}

favicon#

The favicon setting specifies the icon that appears in the browser tab. To use the Ansys favicon, add the following code to your project’s Sphinx conf.py file:

html_favicon = ansys_favicon

Version switcher#

The Ansys Sphinx Theme includes a version switcher for switching between different versions of the documentation. To show the version switcher in your documentation, add the following code to your project’s Sphinx conf.py file:

from ansys_sphinx_theme import get_version_match

version = "0.1.0"
switcher_versions = get_version_match(version)
cname = "your_name"
html_theme_options = {
    "switcher": {
        "json_url": f"https://{cname}/versions.json",
        "version_match": switcher_version,
    },
}

The switcher requires a versions.json file that contains the versions of the documentation and their URLs in the given json_url. For more information, see PyAnsys multi-version documentation in the PyAnsys developer’s guide.

PDF cover page#

The Ansys Sphinx Theme includes a PDF cover page that you can customize. To customize the PDF cover page, see PDF cover page.

Custom CSS#

You can add custom CSS to the Ansys Sphinx Theme by creating a directory named _static/css in your documentation and adding the following code to your project’s Sphinx conf.py file:

html_static_path = ["_static"]
html_css_files = ["css/custom.css"]

Here is an example of a custom CSS file that changes the background color of the body to black and the text color to white:

.body {
    background-color: black;
   color: white;
}