Extensions#
This page contains the shipped extensions that seamlessly integrate with this theme to enhance documentation functionality.
Linkcode extension#
The Linkcode extension automatically adds “Source” links to the documentation for Python, C, C++, and JavaScript objects. It allows you to link to the source code hosted on GitHub.
Installation#
To use the ansys-sphinx-theme
linkcode extension, you need to add it to the Sphinx configuration:
Add the following line in the
conf.py
file:
extensions = ["ansys_sphinx_theme.extension.linkcode"]
Configuration options#
The Linkcode extension provides a way to configure its behavior by using certain options within your conf.py
file.
Depending on your preferred approach, you can utilize the direct
configuration options or the html_context
dictionary to streamline your settings.
If both sets of configuration options are given, the direct configuration options (that is, link_code_library
,
link_code_source
, link_code_branch
) has
precedence over the corresponding settings in the html_context
dictionary.
Direct configuration options#
link_code_library
: The user/repository name where the source code is hosted. For example,ansys/ansys-sphinx-theme
.link_code_source
(str, optional, default: ‘’): The relative path of the source code file within the repository. For example,src
.link_code_branch
(str, optional, default: ‘main’): The GitHub branch. It can be a specific version likemain
ordev
.
If the link_code_source
and link_code_branch
options are not provided in the configuration,
the following default values are used:
link_code_source
: An empty string (''
). This links to the root of the repository.link_code_branch
:main
. This is the default branch name used if no branch is specified.
# Example of setting direct configuration in example
link_code_library = "username/repo-name"
link_code_source = "src"
link_code_branch = "dev"
Using html_context
dictionary#
You also have the option to centralize your GitHub-related configuration by incorporating it
directly into the html_context
dictionary within your conf.py
file. This approach allows you to
minimize redundancy and manage the GitHub-related information more effectively for the extension:
# Example of setting GitHub-related configuration in conf.py
html_context = {
"github_user": "<your-github-org>",
"github_repo": "<your-github-repo>",
"github_version": "<your-branch>",
"source_path": "<path-from-root-to-your-source_file>",
}
With this setup, you can fine-tune your configuration according to your preferences and requirements,
enhancing the integration of the linkcode
extension into your documentation.