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:

  1. 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 like main or dev.

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.