Using this Theme

Install this theme with:

pip install pyansys-sphinx-theme

If you are are new to Sphinx, see the Sphinx Getting Started documentation. Next, modify your Sphinx conf.py file to use html_theme = 'pyansys_sphinx_theme'. Consider using the following conf.py for this repository:

"""Sphinx documentation configuration file."""
from datetime import datetime

from pyansys_sphinx_theme import __version__
from pyansys_sphinx_theme import pyansys_logo_black

# Project information
project = "pyansys_sphinx_theme"
copyright = f"(c) {datetime.now().year} ANSYS, Inc. All rights reserved"
author = "Ansys Inc."
release = version = __version__

# use the default pyansys logo
html_logo = pyansys_logo_black
html_theme = "pyansys_sphinx_theme"

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

html_short_title = html_title = "PyAnsys Sphinx Theme"


# Sphinx extensions
extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.autosummary",
    "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),
}

# 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"

For additional configuration options, see the Configuration topic for the PyData Sphinx theme, which is the basis for the style of this PyAnsys theme.

Editing the CSS

If you need to edit or append to the css, create a directory named _static/css next to your conf.py file . Create your custom.css file in this directory. For example:

body {
 font-family: 'Source Sans Pro', sans-serif;
 color: black;
 padding-top:calc(var(--pst-header-height))
}
footer{display:none}
main{
  overflow: auto;
  height: calc(100vh - 3.8rem);
  overflow-y: scroll;
}
.prev-next-bottom{margin-bottom: 6rem}

Next, add the following to your conf.py file:

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

Use your custom.css file to override the CSS style of this theme.

Adding Breadcrumbs

The PyAnsys Sphinx theme supports the display of breadcrumbs on the body of documentation pages to make navigation easier. These breadcrumbs are disabled by default. To add breadcrumbs to the pages of your documentation, in the conf.py file, add "show_breadcrumbs": True to the html_theme_options dictionary.

If you want to add additional ‘root’ breadcrumbs, such as to the PyAnsys Documentation homepage, add them to the html_theme_options dictionary as a list of tuples with the "additional_breadcrumbs" key. The tuples are of the form ("Link text", "url").

For example, this theme uses the following html_theme_options:

html_theme_options = {
    "github_url": "https://github.com/pyansys/pyansys-sphinx-theme",
    "show_prev_next": False,
    "show_breadcrumbs": True,
    "additional_breadcrumbs":
}

When on the module homepage, a breadcrumb will be displayed with the homepage title. However, this title is not accessible to Sphinx from other documentation pages. Therefore, the html_short_title is used as the display text for the documentation homepage breadcrumb. To ensure a consistent user experience you should ensure the html_short_title (or optionally html_title if html_short_title is not used) is set to the same value as the title of the index.rst page. For example:

html_short_title = html_title = 'PyAnsys Sphinx Theme'

If you want to use the version number in the index.rst title, use |version| to include the package version number.