.. _ref_user_guide_html_theme: HTML theme options ================== In the Sphinx configuration (``conf.py``) file in the ``doc`` directory, you can use the ``html_theme_options`` dictionary to customize the Ansys Sphinx theme. Table of contents ----------------- .. table:: :class: datatable =========================================== ============== ========================================================================================== Option Type Description =========================================== ============== ========================================================================================== :ref:`show_breadcrumbs` bool Show breadcrumbs at the top of each page. :ref:`add_hide_icons_in_navbar` list Add and hide icons in the navigation bar. :ref:`static_search` list Additional static search options to customize the search experience. :ref:`cheat_sheets` list Add a cheat sheet to the left navigation pane of your documentation. :ref:`whats_new` list Show a "What's new" section in the left navigation pane. :ref:`secondary_sidebar` list Control the secondary sidebar on each page. :ref:`navigation_bar_dropdown` list Add a dropdown navigation bar to the top of your documentation. :ref:`announcement_banner` list Add an announcement banner to the top of your documentation pages. :ref:`mcp_server` dict Promote an MCP server on the landing page with a banner linking to its repository. =========================================== ============== ========================================================================================== .. _show_breadcrumbs: Show breadcrumbs ---------------- Showing breadcrumbs at the top of your documentation pages makes navigation easier. Breadcrumbs are shown by setting ``"show_breadcrumbs": True``. To add additional *root* breadcrumbs, ``"additional_breadcrumbs"`` is set to a list of tuples in this form: ``("Link text", "url")``. This ``html_theme_options`` dictionary show breadcrumbs, including a root breadcrumb for the documentation landing page for the Ansys repository: .. code:: python html_theme_options = { "github_url": "https://github.com/ansys/ansys-sphinx-theme", "show_prev_next": True, "show_breadcrumbs": True, "additional_breadcrumbs": [ ("PyAnsys", "https://docs.pyansys.com/"), ], } When you are on the landing page for your documentation, the breadcrumb shows the title for this page. However, Sphinx cannot access this title from other documentation pages. Thus, after ``html_theme_options`` dictionary, you must set ``html_short_title`` to the display text to use for this breadcrumb. To ensure a consistent user experience, always set the ``html_short_title`` (or optionally ``html_title`` if ``html_short_title`` is not used) to the library name. For example, in the ``conf.py`` file for the Ansys Sphinx Theme, this line is added after the ``html_theme_options`` dictionary: .. code:: python html_short_title = html_title = "Ansys Sphinx Theme" If you want the title for your documentation's main ``index.rst`` file to show the version, include ``|version|`` in the title: .. code:: python html_short_title = html_title = "Ansys Sphinx Theme |version|" .. _add_hide_icons_in_navbar: Add and hide icons in the navigation bar ---------------------------------------- The navigation bar shows two icons on the right by default. The first is for switching between light and dark modes. The second is for going to the library's GitHub repository. - For comprehensive information on adding custom link behavior, see `Add custom attributes to icon links `_ in the PyData Theme documentation. - For comprehensive information on how to use Font Awesome to add icons, see `How To Add Icons `_ in the Font Awesome documentation. The following sections explain how to add icons and hide icons. Add icons ~~~~~~~~~ In the ``conf.py`` file, the ``html_theme_options`` dictionary has a child ``icon_links`` dictionary. To add icons to the navigation bar, add them to the ``icon_links`` dictionary. For each icon to add, specify its ``name``, the associated ``url``, the ``icon``, and the ``type``. This example adds an icon for sending an email: .. code-block:: pycon html_theme_options = { "icon_links": [ dict(name="Mail", url="mailto:me", icon="fas fa-envelope") ], ... } Hide icons ~~~~~~~~~~ To hide icons so that they do not show in the navigation bar, add their names to the ``hidden_icons`` dictionary: .. code-block:: pycon html_theme_options = { "hidden_icons": ["GitHub"], ... } If you want to hide all icons, use the ``show_icons`` Boolean variable: .. code-block:: pycon html_theme_options = { "show_icons": False, ... } .. _static_search: Static search options ---------------------- The Ansys Sphinx theme supports static search options to customize the search experience. The static search bar is created using ``Fuse.js``. You can provide `all options `_ supported by ``Fuse.js`` through the ``static_search`` dictionary in the ``html_theme_options``. To improve the search performance, a debounce function is available. By default, a delay of 300 milliseconds is applied. To modify this value, declare the ``delay`` key in the ``static_search`` dictionary with a value specifying the amount of milliseconds to wait before executing the search. A value of ``0`` disables the debounce function. Additionally, you can decide the limit of the search results by setting the ``limit`` key in the ``static_search`` dictionary. The default value is ``10``. To exclude files or directories from the search index, you can use the ``files_to_exclude`` key in the ``static_search`` dictionary. This key is a list of strings representing the directories or files to exclude from the search index. Search result ranking ~~~~~~~~~~~~~~~~~~~~~ By default, the theme assigns the following Fuse.js field weights so that section headings and page titles rank over the body text: .. list-table:: :header-rows: 1 :widths: 20 15 65 * - Field - Default weight - Description * - ``section`` - 3 - Section heading extracted from the page. * - ``title`` - 3 - Full breadcrumb title of the page. * - ``text`` - 1 - Body text of the section. * - ``objectID`` - 0.5 - Internal document identifier. You can override the weights by supplying a ``keys`` list in ``static_search``: .. code-block:: python html_theme_options = { "static_search": { "keys": [ {"name": "section", "weight": 5}, {"name": "title", "weight": 3}, {"name": "text", "weight": 1}, {"name": "objectID", "weight": 0.5}, ], }, } The ``includeScore`` and ``includeMatches`` options are enabled by default so that match highlighting and relevance sorting work out of the box. You can turn off these options if you do not need that information: .. code-block:: python html_theme_options = { "static_search": { "includeScore": False, "includeMatches": False, }, } Here is a full example combining the most commonly used options: .. code-block:: python html_theme_options = { "static_search": { "threshold": 0.5, "limit": 10, "minMatchCharLength": 1, "delay": 300, "files_to_exclude": ["_build", "api/", "examples/sphinx_demo"], }, } .. note:: All other options are available in the `Fuse.js documentation `_. Any key you set takes precedence over the theme defaults; values you omit are filled in automatically. .. note:: Serve locally your documentation using the ``python -m http.server -d /path/to/docs/html/`` to have a live-preview of your search results. This method is compliant with the `CORS policy `_ and allows to load the generated resource files containing the indices of your documentation. The search bar does not work if you open the HTML files directly in the browser. To open the documentation in a local server, run the following command in the directory where the HTML files are located: .. code-block:: bash python -m http.server Then, open the browser and go to ``http://localhost:8000``. Advanced search options ~~~~~~~~~~~~~~~~~~~~~~~ The Ansys Sphinx theme supports advanced search capabilities to enhance the user experience. These options can be configured through the ``html_theme_options`` dictionary in your ``conf.py`` file. Multi-index search ^^^^^^^^^^^^^^^^^^ To enable search across multiple documentation sources, use the ``search_extra_sources`` key. This key should be a dictionary where each key is the name of the source and the value is the URL to that source. **Example:** .. code-block:: python html_theme_options = { "search_extra_sources": { "PyMAPDL": "https://mapdl.docs.pyansys.com/version/stable/", "PyAnsys": "https://docs.pyansys.com/version/stable/", }, } Search filters ^^^^^^^^^^^^^^ To organize and group search results, you can define custom filters using the ``search_filters`` key. This key should be a dictionary where each key represents a filter label and the corresponding value is a list of directories or file paths that belong to that filter. **Example:** .. code-block:: python html_theme_options = { "search_filters": { "User Guide": [ "user-guide/", "getting-started/", "index/", ], "Release Notes": ["changelog"], "Examples": ["examples/"], "Contributing": ["contribute/"], }, } The filters appears as clickable options in the search interface, allowing users to refine their results by content type. The search filters are displayed as below: .. image:: ../_static/search_filter.png :alt: Search filters .. _cheat_sheets: Cheat sheets ------------ If a cheat sheet has been created for your PyAnsys library, with ``quarto``, you can add it to the left navigation pane of your documentation. In the ``html_theme_options`` dictionary, you add a child dictionary named ``cheatsheet`` that contain these keys, in the order given: #. ``file``: filename including the extension of the cheat sheet. If the file is inside a directory, include the directory name relative to the root of the documentation. For example, if the cheat sheet is in the ``getting_started`` directory, the filename is ``getting_started/cheat_sheet.qmd``. #. ``title``: Title of the cheat sheet to be displayed in the left navigation pane. #. ``pages``: List of names for the pages to include the cheat sheet on. If no value is provided, the cheat sheet is displayed only on the main ``index.html`` file. #. ``version``: Version of the cheat sheet. If no value is provided, the version is ``main`` by default. Here is an example of how to add the ``cheatsheet`` dictionary to the `html_theme_options`` dictionary: .. code-block:: python html_theme_options = ( { "cheatsheet": { "file": "", "title": "", "version": "<version of the cheat sheet>", "pages": "<list of names for the pages to include the cheat sheet on>", # Optional }, }, ) Here is an example of how to show a thumbnail of a PyMAPDL cheat sheet in the left navigation pane of its main ``index.rst`` file and the ``learning.rst`` file in its "Getting started" section: .. code-block:: python html_theme_options = ( { "cheatsheet": { "file": "getting_started/cheat_sheet.qmd", "title": "My awesome cheat sheet", "version": f"{version}", "pages": ["index", "getting_started/learning"], }, }, ) .. note:: To use this feature, you must have the `quarto <https://quarto.org/>` package installed. To create thumbnails of generated PDF files, the theme is using `pdf2image`. So you should have the ``poppler`` package installed in your system. For more information, see the `pdf2image documentation <https://pypi.org/project/pdf2image/>`_. .. _whats_new: What's new section ------------------ The "What's new" section is an option that allows you to highlight new features in your library for each minor version within the changelog file. To install the "What's new" dependencies from ansys-sphinx-theme, run the following command: .. code-block:: bash pip install ansys-sphinx-theme[changelog] To get started, create a YAML file named ``whatsnew.yml`` in the ``doc/changelog.d`` directory. The YAML file should contain the following structure: .. code-block:: yaml fragments: - title: Feature title version: 0.2.0 # The version the feature is introduced content: | Feature description in RST format. - title: Another feature title version: 0.1.2 content: | Feature description in RST format. The dropdown generation only supports the following RST formats in the "content" field: - Bold: Use double asterisks to wrap the text. - Italics: Use single asterisks to wrap the text. - Code samples: Use single or double backticks to wrap the text. - Links: Use the following format to include links: .. code-block:: rst `link text <https://www.example.com>`_ - Code blocks: Use the following format to include code blocks: .. code-block:: rst .. code:: python print("hello world") If a format is used in the ``content`` field that does not fall into the categories above, it is not be rendered correctly. To enable the **What's new** section and sidebar in the changelog file, add the following dictionary to the ``html_theme_options`` dictionary: .. code-block:: python html_theme_options = ( { "whatsnew": { "whatsnew_file_path": "../changelog.d/whatsnew.yml", "changelog_file_path": "changelog.rst", "sidebar_pages": ["changelog"], "sidebar_no_of_headers": 3, # Optional "sidebar_no_of_contents": 3, # Optional }, }, ) The dictionary contains the following keys: - ``whatsnew_file_path``: Path to the YAML file containing what's new content local to the ``doc/source`` directory. If not provided, the what's new section is not generated. - ``changelog_file_path``: Path to the ``changelog.rst`` file local to the ``doc/source`` directory. If not provided, the **What's new** section is not generated. - ``sidebar_pages``: List of names for the pages to include in the **What's new** sidebar. If not provided, the **What's new** sidebar is not shown. - ``sidebar_no_of_headers``: Number of minor version sections to display in the **What's new** sidebar. By default, it displays three version sections in the sidebar. - ``sidebar_no_of_contents``: Number of what's new content to display under each minor version in the what's new sidebar. If not provided, it displays all dropdowns by default. The following images show a sample "What's new" section and sidebar in the changelog file: .. tab-set:: .. tab-item:: What's new section .. image:: ../_static/whatsnew_section.png :alt: What's new section .. tab-item:: What's new sidebar .. image:: ../_static/whatsnew_sidebar.png :alt: What's new sidebar .. note:: If you are displaying both the **What's new** and **Cheat sheet** sections, the **Cheat sheet** section is shown first in the left navigation pane, followed by the **What's new** section to maintain sidebar consistency. .. _navigation_bar_dropdown: Navigation bar dropdown ------------------------ This theme supports dropdown navigation bars. The layout is declared using a YAML file contained at any level in the ``doc/source`` directory. The file path is relative to the ``doc/source`` directory,and must be specified in the ``html_theme_options`` dictionary. - ``navigation_yaml_file``: The path to the YAML file containing the navigation structure. .. code:: python html_theme_options = { ..., "navigation_dropdown": { "layout_file": "navbar.yml", # Relative path to the YAML file }, } Each entry in the YAML file may include the following fields: - **file.** The relative path to the documentation file, based on the doc/source directory. - **title.** The text displayed for the link in the dropdown navigation menu. - **sections.** A list of nested navigation items. Each section can specify its own file, title, and an optional caption to provide a brief description. .. code:: yaml - file: api/index title: "API Reference" - file: examples title: "Examples" sections: - file: examples/sphinx-design.rst title: "Sphinx Design Examples" caption: Examples of using Sphinx design features - file: examples/nbsphinx title: "Nbsphinx Examples" caption: Examples of using Nbsphinx for Jupyter Notebooks .. warning:: You must declare the complete layout of the dropdown navigation bar in the YAML file. Sphinx does not resolve it automatically. .. _secondary_sidebar: Secondary sidebar ----------------- The right-hand secondary sidebar shows the **"On this page"** table of contents (TOC), which lists the section anchors for the current page. It also contains the **Edit this page** and **View source** links. Hide the page TOC globally ~~~~~~~~~~~~~~~~~~~~~~~~~~ Set ``"show_page_toc": False`` to hide the page TOC on every page. The **Edit this page** and **View source** links remain visible: .. code:: python html_theme_options = { "show_page_toc": False, } Show the page TOC inside the primary sidebar ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When the secondary sidebar TOC is turned off by with ``"show_page_toc": False``, you can move the TOC into the primary (left-hand) sidebar instead by setting ``"show_page_toc_in_primary_sidebar": True``. .. code:: python html_theme_options = { "show_page_toc": False, "show_page_toc_in_primary_sidebar": True, } The TOC entries are injected directly under the current page's entry in the section navigation tree. A small chevron toggle (``›``) appears beside the page link. Clicking it expands or collapses the entries manually. As you scroll through the page, the TOC auto-expands and highlights the active section heading automatically. Hide the **View source** button globally ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Set ``"show_source_button": False`` to remove the **View source*** link from every page. The page TOC and **Edit this page** link remain visible: .. code:: python html_theme_options = { "show_source_button": False, } Both options can be combined: .. code:: python html_theme_options = { "show_page_toc": False, "show_source_button": False, } Control the secondary sidebar per page ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ For finer control, use the ``secondary_sidebar_items`` option from `pydata-sphinx-theme <https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/layout.html#secondary-sidebar-right>`_. You can pass a list of item names (applied globally) or a dictionary with glob patterns as keys (applied per page). .. code:: python html_theme_options = { # Remove the page TOC from all pages but keep other items. "secondary_sidebar_items": { "**": ["edit-this-page", "sourcelink"], }, } .. code:: python html_theme_options = { # Show the page TOC on regular pages; hide it on API and index pages. "secondary_sidebar_items": { "**": ["page-toc", "edit-this-page", "sourcelink"], "api/**": ["edit-this-page", "sourcelink"], "index": [], }, } Control the TOC depth ~~~~~~~~~~~~~~~~~~~~~~ Use ``show_toc_level`` to set how many heading levels are expanded by default in the page TOC. The default is ``1``, which causes only top-level headings to be shown. This code would show h2 and h3 headings by default: .. code:: python html_theme_options = { "show_toc_level": 2, # Expand h2 and h3 entries by default } Hide the page TOC on a single page ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To suppress the entire secondary sidebar for a single RST page without changing the ``conf.py`` file, add the following metadata at the very top of the file: .. code:: rst :html_theme.sidebar_secondary.remove: Page title ========== ... .. _announcement_banner: Announcement banner ------------------- The Ansys Sphinx Theme supports announcement banners that can be displayed at the top of documentation pages. These banners can be used to communicate important information, such as product updates, deprecation notices, maintenance alerts, or other announcements. To configure an announcement banner, use the ``announcement_banner`` option in the ``html_theme_options`` dictionary of your ``conf.py`` file. This option accepts a list of announcement dictionaries, as shown in the following example: .. code:: python html_theme_options = { "announcement_banner": [ { "message": "Welcome to the Ansys Sphinx Theme documentation!", "type": "info", }, { "message": "This release is deprecated. Please upgrade.", "type": "warning", "link": "https://docs.pyansys.com/version/stable/", }, { "message": "Critical security patch required.", "type": "error", }, { "message": "New features available in the latest release.", "type": "success", }, ], } Each announcement supports the following keys: - ``message``: Text displayed in the announcement banner. - ``type``: Type of announcement. Supported values are: - ``info``: Informational messages. - ``success``: Successful operations or positive updates. - ``warning``: Warnings or deprecation notices. - ``error``: Critical alerts or issues requiring immediate attention. - ``link`` *(optional)*: URL associated with the announcement. When provided, the banner message becomes clickable and directs users to the specified URL for additional information. Announcement banners follow this priority order: **Error > Warning > Success > Info**. When multiple announcement types are configured, the banner adopts the highest-priority type. For instance, if both Error and Warning announcements are available, the landing page banner displays with the Error styling. The order of the announcements in the list determines their display order, with the first announcement appearing at the top of the banner. For example, for the configuration above, below is how the announcement banner appears in the documentation: .. image:: ../_static/announcement_banner.png :alt: Announcement banner When the user clicks on the ``view`` button, the banner expands to show all announcements in the order they are defined in the configuration. .. image:: ../_static/announcement_banner_expanded.png :alt: Expanded announcement banner .. _mcp_server: MCP server banner ----------------- Many Ansys libraries provide a companion `Model Context Protocol (MCP) <https://modelcontextprotocol.io/>`_ server that exposes library functionality to AI assistants and tools. To promote the MCP server from your library's documentation landing page, add the ``mcp_server`` dictionary to ``html_theme_options`` in your ``conf.py`` file: .. code-block:: python html_theme_options = { ..., "mcp_server": { "url": "https://github.com/ansys/pymechanical-mcp", "project_name": "PyMechanical MCP Server", }, } The dictionary supports the following keys: - ``url`` *(required)*: URL pointing to the MCP server repository or documentation. - ``project_name`` *(optional)*: Human-readable name for the MCP server. Defaults to ``"MCP Server"`` if not provided. When configured, a banner is displayed at the top of the documentation landing page (``index.html``). The banner includes: - A brief description inviting users to connect their AI assistant to the library. - A **Learn more** link that opens the configured ``url`` in a new tab. The banner is shown **only on the landing page** and does not appear on any other page. Example configuration for ``PyMechanical``: .. code-block:: python html_theme_options = { "github_url": "https://github.com/ansys/pymechanical", "mcp_server": { "url": "https://github.com/ansys/pymechanical-mcp", "project_name": "PyMechanical MCP Server", }, }