feat: add link code extension (#269)

Co-authored-by: Jorge Martínez <[email protected]>
Co-authored-by: Maxime Rey <[email protected]>
Co-authored-by: Roberto Pastor Muela <[email protected]>

Author: 4 people

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/extensions.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": "[email protected]",
+    "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/extensions.rst

@@ -0,0 +1,79 @@
+.. _ref_user_guide_extension:
+
+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:
+
+.. code-block:: python
+
+    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.
+
+.. code-block:: python
+
+  # 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:
+
+.. code-block:: python
+
+   # 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.

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_extension`
+  
 .. 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
+   extensions
 

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.10.2"
@@ -107,6 +109,103 @@ 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
+        Sphinx application instance for rendering the documentation.
+    pagename : str
+        Name of the current page.
+    templatename : str
+        Name of the template being used.
+    context : dict
+        Context dictionary for the page.
+    doctree : document
+        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
+            Link to the GitHub edit interface.
+
+        Returns
+        -------
+        str
+            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 "_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}.{domain}"  # noqa: E501
+                    else:
+                        return f"http://github.com/{github_user}/{github_repo}/edit/{kind}/{modname}.{domain}"  # 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 +261,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."""