fix: add home section (#769)

Co-authored-by: pyansys-ci-bot <[email protected]>
Co-authored-by: Jorge Martínez <[email protected]>
Co-authored-by: Sébastien Morais <[email protected]>

Author: 4 people

doc/changelog.d/769.fixed.md

@@ -0,0 +1 @@
+Add home section

pyproject.toml

@@ -30,25 +30,25 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
 ]
 dependencies = [
-    "Sphinx>=6.1.0",
-    "pydata-sphinx-theme>=0.15.4,<0.17",
-    "Jinja2>=3.1.2",
     "importlib-metadata>=4.0",
+    "Jinja2>=3.1.2",
     "pdf2image>=1.17.0",
+    "pydata-sphinx-theme>=0.15.4,<0.17",
     "PyYAML==6.0.2",
+    "Sphinx>=6.1.0",
 ]
 
 [project.optional-dependencies]
 autoapi = [
+    "astroid>=3.0,<4.0",
     "sphinx-autoapi==3.6.0",
     "sphinx-design==0.6.1",
     "sphinx-jinja==2.0.2",
-    "astroid>=3.0,<4.0",
 ]
 doc = [
     "jupytext==1.17.2",
-    "notebook==7.4.5",
     "nbsphinx==0.9.7",
+    "notebook==7.4.5",
     "numpydoc==1.9.0",
     "pandas==2.3.2",
     "Pillow>=9.0",
@@ -63,8 +63,8 @@ doc = [
     "sphinx-gallery==0.19.0",
     "sphinx-jinja==2.0.2",
     "sphinx-notfound-page==1.1.0",
-    "tox==4.28.4",
     "sphinx-theme-builder[cli]==0.2.0b2",
+    "tox==4.28.4",
 ]
 changelog = [
     "PyYAML==6.0.2",

src/ansys_sphinx_theme/__init__.py

@@ -24,11 +24,13 @@
 
 import os
 import pathlib
-from typing import Any, Dict
-import warnings
+import re
+from typing import Any
 
 from docutils import nodes
+from pydata_sphinx_theme.toctree import traverse_or_findall
 from sphinx import addnodes
+from sphinx.addnodes import toctree
 from sphinx.application import Sphinx
 from sphinx.util import logging
 
@@ -70,6 +72,9 @@
 ANSYS_LOGO_LINK = "https://www.ansys.com/"
 PYANSYS_LOGO_LINK = "https://docs.pyansys.com/"
 
+PACKAGE_HOME_HTML_PATTERN = re.compile(r'<a([^>]*?)href="[^"]*index\.html"([^>]*?)>\s*Home\s*</a>')
+
+
 # make logo paths available
 ansys_favicon = str((LOGOS_PATH / "ansys-favicon.png").absolute())
 ansys_logo_black = str((LOGOS_PATH / "ansys_logo_black_cropped.jpg").absolute())
@@ -290,7 +295,7 @@ def fix_edit_link_page(link: str) -> str:
 
 
 def update_footer_theme(
-    app: Sphinx, pagename: str, templatename: str, context: Dict[str, Any], doctree: nodes.document
+    app: Sphinx, pagename: str, templatename: str, context: dict[str, Any], doctree: nodes.document
 ) -> None:
     """Update the version number of the Ansys Sphinx theme in the footer.
 
@@ -380,10 +385,12 @@ def configure_theme_logo(app: Sphinx):
 
     if logo_option == "ansys":
         theme_options["logo"] = ansys_logo
-        theme_options["logo_link"] = theme_options.get("logo_link", ANSYS_LOGO_LINK)
+        # Ansys logo should link to the ANSYS homepage
+        theme_options["logo_link"] = ANSYS_LOGO_LINK
     elif logo_option == "pyansys":
         theme_options["logo"] = pyansys_logo
-        theme_options["logo_link"] = theme_options.get("logo_link", PYANSYS_LOGO_LINK)
+        # PyAnsys logo should link to the PyAnsys Meta documentation
+        theme_options["logo_link"] = PYANSYS_LOGO_LINK
     elif logo_option == "no_logo":
         theme_options["logo"] = None
 
@@ -474,7 +481,85 @@ def update_search_sidebar_context(
     context["sidebars"] = sidebar
 
 
-def setup(app: Sphinx) -> Dict:
+def on_doctree_resolved(app: Sphinx, doctree: nodes.document, docname: str) -> None:
+    """Add a 'Home' entry to the root TOC.
+
+    Parameters
+    ----------
+    app : Sphinx
+        Sphinx application instance for rendering the documentation.
+    doctree : nodes.document
+        Document tree for the page.
+    docname : str
+        Name of the current document.
+
+    Notes
+    -----
+    This function checks if the 'Home' entry already exists in the root TOC.
+    If it does not exist, it adds the 'Home' entry at the beginning of the TOC.
+    The 'Home' entry links to the index page of the documentation.
+    """
+    index_page = app.config.root_doc or app.config.master_doc or "index"
+    root_toc = app.env.tocs[app.config.root_doc]
+    for toc in traverse_or_findall(root_toc, toctree):
+        if not toc.attributes.get("entries"):
+            return
+
+        for title, page in toc.attributes["entries"]:
+            if title == "Home":
+                return
+
+        home_entry = (
+            nodes.Text("Home"),
+            index_page if index_page != docname else None,
+        )
+        # Insert 'Home' entry at the beginning of the TOC
+        toc.attributes["entries"].insert(0, home_entry)
+
+
+def add_tooltip_after_build(app: Sphinx, exception):
+    """Add tooltips to 'Home' links after the build process.
+
+    Parameters
+    ----------
+    app : Sphinx
+        Sphinx application instance for rendering the documentation.
+    exception : Exception
+        Exception raised during the build process.
+
+    Returns
+    -------
+    None
+    """
+    if exception:
+        return
+
+    outdir = pathlib.Path(app.outdir)
+
+    project_name = "Package Home"
+
+    if app.config.html_short_title:
+        project_name = f"{app.config.html_short_title} home"
+    elif app.config.project:
+        project_name = f"{app.config.project} home"
+
+    for html_file in outdir.rglob("*.html"):
+        text = html_file.read_text(encoding="utf-8")
+
+        def replacer(match):
+            attrs_before, attrs_after = match.groups()
+            full_attrs = f"{attrs_before}{attrs_after}"
+            if "title=" in full_attrs:
+                return match.group(0)  # don't duplicate title
+            return f'<a{attrs_before}href="index.html"{attrs_after} title="{project_name}">\n    Home\n</a>'  # noqa: E501
+
+        new_text = PACKAGE_HOME_HTML_PATTERN.sub(replacer, text)
+
+        if new_text != text:
+            html_file.write_text(new_text, encoding="utf-8")
+
+
+def setup(app: Sphinx) -> dict:
     """Connect to the Sphinx theme app.
 
     Parameters
@@ -516,14 +601,15 @@ def setup(app: Sphinx) -> Dict:
     if whatsnew_file and changelog_file:
         app.connect("doctree-read", add_whatsnew_changelog)
         app.connect("doctree-resolved", extract_whatsnew)
-
     app.connect("html-page-context", add_sidebar_context)
     app.connect("html-page-context", update_footer_theme)
     app.connect("html-page-context", fix_edit_html_page_context)
     app.connect("html-page-context", update_search_sidebar_context)
     app.connect("html-page-context", update_template_context)
+    app.connect("doctree-resolved", on_doctree_resolved)
 
     app.connect("build-finished", replace_html_tag)
+    app.connect("build-finished", add_tooltip_after_build)
     if use_ansys_search:
         app.connect("build-finished", create_search_index)