feat: add link code extension

doc/source/_templates/message.html

@@ -0,0 +1,7 @@
+<div class="sidebar-message">
+  See the new feature of linkcode extension in
+  <a href="https://sphinxdocs.ansys.com/version/dev/user_guide/link_code.html"
+    >dev docs.</a
+  >
+  Your contributions are welcome!
+</div>

doc/source/conf.py

@@ -20,6 +20,10 @@
     watermark,
 )
 
+ANNOUNCEMENT_URL = (
+    "https://raw.githubusercontent.com/ansys/ansys-sphinx-theme/main/doc/_templates/message.html"
+)
+
 # Project information
 project = "ansys_sphinx_theme"
 copyright = f"(c) {datetime.now().year} ANSYS, Inc. All rights reserved"
@@ -45,6 +49,7 @@
 html_theme_options = {
     "github_url": "https://github.com/ansys/ansys-sphinx-theme",
     "contact_mail": "pyansys.support@ansys.com",
+    "use_edit_page_button": True,
     "additional_breadcrumbs": [
         ("PyAnsys", "https://docs.pyansys.com/"),
     ],
@@ -64,6 +69,7 @@
             f"ansys-sphinx-theme-v{convert_version_to_pymeilisearch(__version__)}": "ansys-sphinx-theme",  # noqa: E501
         },
     },
+    "announcement": ANNOUNCEMENT_URL,
 }
 
 html_short_title = html_title = "Ansys Sphinx Theme"

doc/source/user_guide/index.rst

@@ -13,7 +13,8 @@ While the Ansys Sphinx theme is often used as is, you can customize the followin
 - :ref:`ref_user_guide_html_theme`
 - :ref:`ref_user_guide_pdf_cover`
 - :ref:`ref_user_guide_404_page`
-
+- :ref:`ref_user_guide_link_code`
+
 .. toctree::
    :hidden:
    :maxdepth: 2
@@ -22,4 +23,5 @@ While the Ansys Sphinx theme is often used as is, you can customize the followin
    options
    pdf
    404_page
+   link_code
 

doc/source/user_guide/link_code.rst

@@ -0,0 +1,47 @@
+.. _ref_user_guide_link_code:
+
+Linkcode extension
+==================
+
+The Linkcode extension automatically adds "View 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:
+
+   .. code-block:: python
+
+      extensions = ["ansys_sphinx_theme.extension.linkcode"]
+
+Configuration options
+---------------------
+
+The Linkcode extension supports the following configuration options in your `conf.py` file:
+
+- ``link_code_library`` (str, optional):
+  The user/repository name where the source code is hosted. For example, ``ansys/ansys-sphinx-theme``.
+
+- ``link_code_source`` (str, optional):
+  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``.
+
+You can also set the `link_code_library`, `link_code_source`, `link_code_branch`,
+and other GitHub-related configuration options directly in the `html_context` dictionary in your `conf.py` file.
+By doing so, you can avoid redundancy and centralize the GitHub-related information for the extension:
+
+.. code-block:: python
+
+   # Example of setting GitHub-related configuration in conf.py
+   html_context = {
+       # "github_url": "https://github.com", # or your GitHub Enterprise site
+       "github_user": "<your-github-org>",
+       "github_repo": "<your-github-repo>",
+       "github_version": "<your-branch>",
+       "source_path": "<path-from-root-to-your-source_file>",
+   }

doc/styles/Vocab/ANSYS/accept.txt

@@ -4,4 +4,10 @@ ansys
 Ansys Sphinx Theme
 boolean
 datatable
-MeiliSearch
+MeiliSearch
+Linkcode
+linkcode
+link_code_library
+link_code_source
+link_code_branch
+html_context

src/ansys_sphinx_theme/__init__.py

@@ -3,8 +3,10 @@
 from typing import Any, Dict
 
 from docutils.nodes import document
+from sphinx import addnodes
 from sphinx.application import Sphinx
 
+from ansys_sphinx_theme.extension.linkcode import DOMAIN_KEYS, sphinx_linkcode_resolve
 from ansys_sphinx_theme.latex import generate_404  # noqa: F401
 
 __version__ = "0.11.dev0"
@@ -107,6 +109,106 @@ def setup_default_html_theme_options(app):
     app.config.html_theme_options.setdefault("collapse_navigation", True)
 
 
+def fix_edit_html_page_context(
+    app: Sphinx, pagename: str, templatename: str, context: dict, doctree: document
+) -> None:
+    """Add a function that Jinja can access for returning an "edit this page" link .
+
+    This function creates an "edit this page" link for any library.
+    The link points to the corresponding file on the main branch.
+
+    Parameters
+    ----------
+    app : Sphinx
+        The Sphinx application instance for rendering the documentation.
+    pagename : str
+        The name of the current page.
+    templatename : str
+        The name of the template being used.
+    context : dict
+        The context dictionary for the page.
+    doctree : document
+        The document tree for the page.
+
+    Notes
+    -----
+    .. [1] Originally implemented by `Alex Kaszynski <https://github.com/akaszynski>`_ in
+    `PyVista <https://github.com/pyvista/pyvista>`_,
+    see https://github.com/pyvista/pyvista/pull/4113
+    """
+
+    def fix_edit_link_button(link: str) -> str:
+        """Transform "edit on GitHub" links to the correct URL.
+
+        This function fixes the URL for the "edit this page" link.
+
+        Parameters
+        ----------
+        link : str
+            The link to the GitHub edit interface.
+
+        Returns
+        -------
+        str
+            The link to the corresponding file on the main branch.
+        """
+        github_user = context.get("github_user", "")
+        github_repo = context.get("github_repo", "")
+        github_source = context.get("source_path", "")
+        kind = context.get("github_version", "")
+
+        if pagename.startswith("examples") and "index" not in pagename:
+            return f"http://github.com/{github_user}/{github_repo}/edit/{kind}/{pagename}.py"
+
+        elif "_autosummary" in pagename:
+            for obj_node in list(doctree.findall(addnodes.desc)):
+                domain = obj_node.get("domain")
+                for signode in obj_node:
+                    if not isinstance(signode, addnodes.desc_signature):
+                        continue
+                    # Convert signode to a specified format
+                    info = {}
+                    for key in DOMAIN_KEYS.get(domain, []):
+                        value = signode.get(key)
+                        if not value:
+                            value = ""
+                        info[key] = value
+                    if not info:
+                        continue
+                    # This is an API example
+                    return sphinx_linkcode_resolve(
+                        domain=domain,
+                        info=info,
+                        library=f"{github_user}/{github_repo}",
+                        source_path=github_source,
+                        github_version=kind,
+                        edit=True,
+                    )
+
+        elif "autoapi" in pagename:
+            for obj_node in list(doctree.findall(addnodes.desc)):
+                domain = obj_node.get("domain")
+                if domain != "py":
+                    return link
+
+                for signode in obj_node:
+                    if not isinstance(signode, addnodes.desc_signature):
+                        continue
+
+                    fullname = signode["module"]
+                    modname = fullname.replace(".", "/")
+
+                    if github_source:
+                        return f"http://github.com/{github_user}/{github_repo}/edit/{kind}/{github_source}/{modname}.py"  # noqa: E501
+                    else:
+                        return f"http://github.com/{github_user}/{github_repo}/edit/{kind}/{modname}.py"  # noqa: E501
+
+        else:
+            return link
+
+    context["fix_edit_link_button"] = fix_edit_link_button
+
+
 def update_footer_theme(
     app: Sphinx, pagename: str, templatename: str, context: Dict[str, Any], doctree: document
 ) -> None:
@@ -162,9 +264,8 @@ def setup(app: Sphinx) -> Dict:
     app.add_js_file("https://cdn.datatables.net/1.10.23/js/jquery.dataTables.min.js")
     app.add_css_file("https://cdn.datatables.net/1.10.23/css/jquery.dataTables.min.css")
     app.connect("html-page-context", update_footer_theme)
-    # Add templates for autosummary
+    app.connect("html-page-context", fix_edit_html_page_context)
     app.config.templates_path.append(str(TEMPLATES_PATH))
-
     return {
         "version": __version__,
         "parallel_read_safe": True,

src/ansys_sphinx_theme/extension/__init__.py

@@ -0,0 +1 @@
+"""A sub-package containing various extensions for the Ansys Sphinx Theme."""