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.
Use MeiliSearch#
MeiliSearch is an open source search engine that allows developers to easily integrate search functionality into their applications.
To use MeiliSearch in your documentation, in the conf.py
file,
a child dictionary named use_meilisearch``is added to the ``html_theme_options
dictionary.
This dictionary contains these keys, in the order given:
host
: Host name of your MeiliSearch instance. If no value is provided, the default public host for PyAnsys is used:https://backend.search.pyansys.com
on port7700
. If added security is needed, you can use theos.getenv()
function to set the instance using an environment variable.api_key
: API key for your MeiliSearch instance. If no value is provided, the default public API key for PyAnsys is used. If added security is needed, you can use theos.getenv()
function to set the key using an environment variable.index_uids
: Dictionary that provides the mapping between the unique identifier (UID) of an index and its corresponding user-friendly name. Each key-value pair in the dictionary represents an index, with the key being the index UID and the value being the index name. The index UID points to an index on the server.
Here is an example of how to configure MeiliSearch for use in the conf.py
file:
import os
use_meilisearch = {
"host": os.getenv("MEILISEARCH_HOST_NAME", ""),
"api_key": os.getenv("MEILISEARCH_API_KEY", ""),
"index_uids": {
"index-uid of current project": "index name to display",
"another-index-uid": "index name to display",
},
}
If your project features multiple documentation versions, it’s crucial to adapt the
index_uids
mapping to accommodate different versions. To ensure seamless search
integration across versions, use the following format to dynamically generate
version-specific index UIDs
:
from ansys_sphinx_theme import convert_version_to_pymeilisearch
use_meilisearch = {
"api_key": os.getenv("MEILISEARCH_PUBLIC_API_KEY", ""),
"index_uids": {
f"ansys-sphinx-theme-v{convert_version_to_pymeilisearch(__version__)}": "ansys-sphinx-theme",
},
}
Here is an example configuration of how to configure MeiliSearch in the conf.py
file
for the Ansys Sphinx Theme:
import os
html_theme_options = {
"use_meilisearch": {
"index_uids": {
"ansys-sphinx-theme-sphinx-docs": "ansys-sphinx-theme",
"pyansys-docs-all-public": "PyAnsys",
},
},
}
With these options set, MeiliSearch is available for performing searches of your documentation.
Note
If you do not set the use_meilisearch
dictionary, the
Ansys Sphinx Theme uses the default search functionality
inherited from the PyData Sphinx Theme.
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
: File name 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 thegetting_started
directory, the file name isgetting_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 mainindex.html
file.
Here is an example of how to add the cheatsheet
dictionary to the html_theme_options` dictionary:
html_theme_options = (
{
"cheatsheet": {
"file": "<file name including the extension 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:
html_theme_options = (
{
"cheatsheet": {
"file": "getting_started/cheat_sheet.qmd",
"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.