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.

PyAnsys tags#

The Ansys Sphinx Theme allows you to add a physics tag in your metadata based on the pyansys category. This can be useful for categorizing content related to specific physics domains, such as Electromagnetics, Structures, or Fluids. You can add a physics tag to your documentation by setting the pyansys_tags option in your project’s Sphinx conf.py file.

html_context = {
    "pyansys_tags": ["Electromagnetics"],
}

which result in the following metadata in your HTML pages:

<meta property="og:site_name" content="PyAnsys" />
<meta name="physics" content="Electromagnetics" />

If you want to add multiple physics tags, you can do so by providing a list of tags:

html_context = {
    "pyansys_tags": ["Electromagnetics", "Structures", "Fluids"],
}

This result in multiple <meta> tags in your HTML pages:

<meta property="og:site_name" content="PyAnsys" />
<meta name="physics" content="Electromagnetics" />
<meta name="physics" content="Structures" />
<meta name="physics" content="Fluids" />

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;
}