From bfe36b5823b7436b601bb1435b9901093dcb96ca Mon Sep 17 00:00:00 2001 From: Revathyvenugopal162 Date: Fri, 1 Aug 2025 15:19:41 +0200 Subject: [PATCH 01/16] fix: add home section --- src/ansys_sphinx_theme/__init__.py | 58 ++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/src/ansys_sphinx_theme/__init__.py b/src/ansys_sphinx_theme/__init__.py index a91e34005..162df947a 100644 --- a/src/ansys_sphinx_theme/__init__.py +++ b/src/ansys_sphinx_theme/__init__.py @@ -472,6 +472,63 @@ def update_search_sidebar_context( # Update the sidebar context context["sidebars"] = sidebar + + +# get the toctree and add Home to the beginning +def add_home_to_toc( + app: Sphinx, pagename: str, templatename: str, context: dict, doctree: nodes.document +) -> None: + """Add 'Home' to the beginning of the table of contents. + + This function adds a 'Home' link to the beginning of the table of contents + for the documentation. It ensures that the 'Home' link is always present + at the top of the table of contents. + + Parameters + ---------- + app : sphinx.application.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 : docutils.nodes.document + Document tree for the page. + """ + + # if not pagename == "index": + # # Only add 'Home' to the TOC if the current page is not the index page + # return + orig_toctree_fn = context.get("toctree") + original_generate = context.get("generate_toctree_html", None) + if not original_generate: + warnings.warn( + "The 'generate_toctree_html' function is not available in the context. " + "This may cause issues with the 'Home' link in the table of contents.", + UserWarning, + ) + print(f"original_generate: {original_generate}") + exit(1) + if callable(original_generate): + def new_generate_toctree_html(kind="sidebar", **kwargs): + html = original_generate(kind=kind, **kwargs) + + if kind != "sidebar": + return html # only modify the sidebar TOC + + home_url = app.builder.get_relative_uri(pagename, app.config.master_doc) + home_html = f''' + + ''' + return home_html + html + + context["generate_toctree_html"] = new_generate_toctree_html def setup(app: Sphinx) -> Dict: @@ -522,6 +579,7 @@ def setup(app: Sphinx) -> Dict: 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("html-page-context", add_home_to_toc) app.connect("build-finished", replace_html_tag) if use_ansys_search: From 432099cde29dae56563ee5bb985d9ad20334c492 Mon Sep 17 00:00:00 2001 From: pyansys-ci-bot <92810346+pyansys-ci-bot@users.noreply.github.com> Date: Tue, 5 Aug 2025 07:58:31 +0000 Subject: [PATCH 02/16] chore: adding changelog file 769.fixed.md [dependabot-skip] --- doc/changelog.d/769.fixed.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 doc/changelog.d/769.fixed.md diff --git a/doc/changelog.d/769.fixed.md b/doc/changelog.d/769.fixed.md new file mode 100644 index 000000000..12687fca1 --- /dev/null +++ b/doc/changelog.d/769.fixed.md @@ -0,0 +1 @@ +Add home section \ No newline at end of file From 7c28eb212098f63affefef62053767f02d9232df Mon Sep 17 00:00:00 2001 From: Revathyvenugopal162 Date: Tue, 5 Aug 2025 10:15:59 +0200 Subject: [PATCH 03/16] fix: update the precommit --- src/ansys_sphinx_theme/__init__.py | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/src/ansys_sphinx_theme/__init__.py b/src/ansys_sphinx_theme/__init__.py index 162df947a..f030159de 100644 --- a/src/ansys_sphinx_theme/__init__.py +++ b/src/ansys_sphinx_theme/__init__.py @@ -472,8 +472,8 @@ def update_search_sidebar_context( # Update the sidebar context context["sidebars"] = sidebar - - + + # get the toctree and add Home to the beginning def add_home_to_toc( app: Sphinx, pagename: str, templatename: str, context: dict, doctree: nodes.document @@ -497,11 +497,9 @@ def add_home_to_toc( doctree : docutils.nodes.document Document tree for the page. """ - # if not pagename == "index": # # Only add 'Home' to the TOC if the current page is not the index page # return - orig_toctree_fn = context.get("toctree") original_generate = context.get("generate_toctree_html", None) if not original_generate: warnings.warn( @@ -512,6 +510,7 @@ def add_home_to_toc( print(f"original_generate: {original_generate}") exit(1) if callable(original_generate): + def new_generate_toctree_html(kind="sidebar", **kwargs): html = original_generate(kind=kind, **kwargs) @@ -519,13 +518,13 @@ def new_generate_toctree_html(kind="sidebar", **kwargs): return html # only modify the sidebar TOC home_url = app.builder.get_relative_uri(pagename, app.config.master_doc) - home_html = f''' + home_html = f""" - ''' + """ return home_html + html context["generate_toctree_html"] = new_generate_toctree_html From 667e260681f6628507a77d09ab212f519ba4043a Mon Sep 17 00:00:00 2001 From: Revathyvenugopal162 Date: Tue, 5 Aug 2025 14:55:15 +0200 Subject: [PATCH 04/16] fix: add docstree resolve --- src/ansys_sphinx_theme/__init__.py | 163 ++++++++++++++++++++++++----- 1 file changed, 138 insertions(+), 25 deletions(-) diff --git a/src/ansys_sphinx_theme/__init__.py b/src/ansys_sphinx_theme/__init__.py index f030159de..41bb64b0e 100644 --- a/src/ansys_sphinx_theme/__init__.py +++ b/src/ansys_sphinx_theme/__init__.py @@ -500,34 +500,146 @@ def add_home_to_toc( # if not pagename == "index": # # Only add 'Home' to the TOC if the current page is not the index page # return - original_generate = context.get("generate_toctree_html", None) - if not original_generate: - warnings.warn( - "The 'generate_toctree_html' function is not available in the context. " - "This may cause issues with the 'Home' link in the table of contents.", - UserWarning, - ) - print(f"original_generate: {original_generate}") - exit(1) - if callable(original_generate): + root_doc = app.config.root_doc # Usually 'index' + root_toc = app.env.tocs.get(root_doc) + + if not root_toc: + return - def new_generate_toctree_html(kind="sidebar", **kwargs): - html = original_generate(kind=kind, **kwargs) + # Find the outermost bullet_list node + outer_bullet_list = next((n for n in root_toc if isinstance(n, nodes.bullet_list)), None) + if not outer_bullet_list: + return + + # Create a new list_item node for Home + home_item = nodes.list_item() + para = nodes.paragraph() + ref = nodes.reference( + internal=True, + refuri=app.builder.get_relative_uri(pagename, app.config.master_doc), + ) + ref += nodes.Text("🏠 Home") + para += ref + home_item += para + + # Insert Home at the top of the bullet list + outer_bullet_list.insert(0, home_item) + + # Update the doctree in env + app.env.tocs[root_doc] = root_toc + # original_toctree = context.get("toctree") + # import json + # JSON_FILE = pathlib.Path("toctree.json") + # if JSON_FILE.exists(): + # with JSON_FILE.open("r", encoding="utf-8") as f: + # context = json.load(f) + # else: + # with JSON_FILE.open("w", encoding="utf-8") as f: + # json.dump(context, f, indent=2, default=str) + + # if not original_toctree: + # warnings.warn( + # "The 'toctree' function is not available in the context. " + # "This may cause issues with the 'Home' link in the table of contents.", + # UserWarning, + # ) + # exit(1) + # exit(1) +# original_toctree = context.get("toctree") + +# if not callable(original_toctree): +# print(original_toctree) +# print("here=========original_toctree is not callable") +# exit(1) +# return # Nothing to patch + +# def new_toctree(*args, **kwargs): +# # Render the normal toctree +# html = original_toctree(*args, **kwargs) + + + +# # Create the Home link HTML +# home_url = app.builder.get_relative_uri(pagename, app.config.master_doc) +# home_html = f""" +# +# """ +# print("home_html", home_html) +# return home_html + html + +# # return html # Don't modify other kinds of toctree (e.g. in page content) + +# context["toctree"] = new_toctree + +from docutils.nodes import Node +from typing import Callable, Iterable, Union + +def traverse_or_findall( + node: Node, condition: Union[Callable, type], **kwargs +) -> Iterable[Node]: + """Triage node.traverse (docutils <0.18.1) vs node.findall. + + TODO: This check can be removed when the minimum supported docutils version + for numpydoc is docutils>=0.18.1. + """ + return ( + node.findall(condition, **kwargs) + if hasattr(node, "findall") + else node.traverse(condition, **kwargs) + ) + +from sphinx.addnodes import toctree as TocTreeNodeClass + +def on_doctree_resolved(app: Sphinx, doctree: nodes.document, docname: str) -> None: + root_toc = app.env.tocs[app.config.root_doc] + for toc in traverse_or_findall(root_toc, TocTreeNodeClass): + # TODO: ↑↑↑ use `root_toc.findall(TocTreeNodeClass)` ↑↑↑ + # once docutils min version >=0.18.1 + # ADD HOME TO THE TOC + if not toc.attributes.get("entries"): + # No entries in the TOC, nothing to do + return + # Check if 'Home' already exists in the TOC + for title, page in toc.attributes["entries"]: + # add home, self to the beginning of the TOC + if title == "Home" and page == docname: + # Home already exists, no need to add it again + return + # if not title == "Home" and page == docname: + # Create a new entry for 'Home', link self to the root document + # This is the link to the root document, which is usually 'index' + # If the root document is not 'index', it will still link to the root document + # This is the link to the root document, which is usually 'index' + home_entry = (nodes.Text("🏠 Home"), app.builder.get_relative_uri(docname, app.config.master_doc)) + # Insert 'Home' at the beginning of the TOC entries + toc.attributes["entries"].insert(0, home_entry) + + + # # Find the top-level bullet list in the doctree + # outer_bullet_list = next((n for n in root_toc if isinstance(n, nodes.bullet_list)), None) + # if not outer_bullet_list: + # return - if kind != "sidebar": - return html # only modify the sidebar TOC + # # Create a new list_item node for Home + # home_item = nodes.list_item() + # para = nodes.paragraph() + # ref = nodes.reference( + # internal=True, + # refuri=app.builder.get_relative_uri(docname, app.config.master_doc), + # ) + # ref += nodes.Text("🏠 Home") + # para += ref + # home_item += para - home_url = app.builder.get_relative_uri(pagename, app.config.master_doc) - home_html = f""" - - """ - return home_html + html + # # Insert Home at the top of the bullet list + # outer_bullet_list.insert(0, home_item) - context["generate_toctree_html"] = new_generate_toctree_html + # # Update the doctree in env + # app.env.tocs[root_doc] = root_toc def setup(app: Sphinx) -> Dict: @@ -578,7 +690,8 @@ def setup(app: Sphinx) -> Dict: 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("html-page-context", add_home_to_toc) + # app.connect("html-page-context", add_home_to_toc, priority=600) + app.connect("doctree-resolved", on_doctree_resolved) app.connect("build-finished", replace_html_tag) if use_ansys_search: From 9329a63add167c8aaf47f059848c4c9bbc0d5e17 Mon Sep 17 00:00:00 2001 From: Revathyvenugopal162 Date: Tue, 5 Aug 2025 14:57:41 +0200 Subject: [PATCH 05/16] fix: add docstree resolve --- src/ansys_sphinx_theme/__init__.py | 31 ++++++++++++------------------ 1 file changed, 12 insertions(+), 19 deletions(-) diff --git a/src/ansys_sphinx_theme/__init__.py b/src/ansys_sphinx_theme/__init__.py index 41bb64b0e..21dac8220 100644 --- a/src/ansys_sphinx_theme/__init__.py +++ b/src/ansys_sphinx_theme/__init__.py @@ -24,11 +24,13 @@ import os import pathlib -from typing import Any, Dict +from typing import Any, Callable, Dict, Iterable, Union import warnings from docutils import nodes +from docutils.nodes import Node from sphinx import addnodes +from sphinx.addnodes import toctree from sphinx.application import Sphinx from sphinx.util import logging @@ -545,6 +547,8 @@ def add_home_to_toc( # ) # exit(1) # exit(1) + + # original_toctree = context.get("toctree") # if not callable(original_toctree): @@ -557,8 +561,7 @@ def add_home_to_toc( # # Render the normal toctree # html = original_toctree(*args, **kwargs) - - + # # Create the Home link HTML # home_url = app.builder.get_relative_uri(pagename, app.config.master_doc) # home_html = f""" @@ -575,12 +578,8 @@ def add_home_to_toc( # context["toctree"] = new_toctree -from docutils.nodes import Node -from typing import Callable, Iterable, Union -def traverse_or_findall( - node: Node, condition: Union[Callable, type], **kwargs -) -> Iterable[Node]: +def traverse_or_findall(node: Node, condition: Union[Callable, type], **kwargs) -> Iterable[Node]: """Triage node.traverse (docutils <0.18.1) vs node.findall. TODO: This check can be removed when the minimum supported docutils version @@ -592,14 +591,10 @@ def traverse_or_findall( else node.traverse(condition, **kwargs) ) -from sphinx.addnodes import toctree as TocTreeNodeClass def on_doctree_resolved(app: Sphinx, doctree: nodes.document, docname: str) -> None: root_toc = app.env.tocs[app.config.root_doc] - for toc in traverse_or_findall(root_toc, TocTreeNodeClass): - # TODO: ↑↑↑ use `root_toc.findall(TocTreeNodeClass)` ↑↑↑ - # once docutils min version >=0.18.1 - # ADD HOME TO THE TOC + for toc in traverse_or_findall(root_toc, toctree): if not toc.attributes.get("entries"): # No entries in the TOC, nothing to do return @@ -610,14 +605,12 @@ def on_doctree_resolved(app: Sphinx, doctree: nodes.document, docname: str) -> N # Home already exists, no need to add it again return # if not title == "Home" and page == docname: - # Create a new entry for 'Home', link self to the root document - # This is the link to the root document, which is usually 'index' - # If the root document is not 'index', it will still link to the root document - # This is the link to the root document, which is usually 'index' - home_entry = (nodes.Text("🏠 Home"), app.builder.get_relative_uri(docname, app.config.master_doc)) + home_entry = ( + nodes.Text("🏠 Home"), + app.builder.get_relative_uri(docname, app.config.master_doc), + ) # Insert 'Home' at the beginning of the TOC entries toc.attributes["entries"].insert(0, home_entry) - # # Find the top-level bullet list in the doctree # outer_bullet_list = next((n for n in root_toc if isinstance(n, nodes.bullet_list)), None) From b92a0ee08fdbf18b16d0b6faf407bbeefe5a9f8d Mon Sep 17 00:00:00 2001 From: Revathyvenugopal162 Date: Tue, 5 Aug 2025 16:53:29 +0200 Subject: [PATCH 06/16] fix: remove html context --- src/ansys_sphinx_theme/__init__.py | 104 ----------------------------- 1 file changed, 104 deletions(-) diff --git a/src/ansys_sphinx_theme/__init__.py b/src/ansys_sphinx_theme/__init__.py index 21dac8220..26bb2ef1b 100644 --- a/src/ansys_sphinx_theme/__init__.py +++ b/src/ansys_sphinx_theme/__init__.py @@ -476,109 +476,6 @@ def update_search_sidebar_context( context["sidebars"] = sidebar -# get the toctree and add Home to the beginning -def add_home_to_toc( - app: Sphinx, pagename: str, templatename: str, context: dict, doctree: nodes.document -) -> None: - """Add 'Home' to the beginning of the table of contents. - - This function adds a 'Home' link to the beginning of the table of contents - for the documentation. It ensures that the 'Home' link is always present - at the top of the table of contents. - - Parameters - ---------- - app : sphinx.application.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 : docutils.nodes.document - Document tree for the page. - """ - # if not pagename == "index": - # # Only add 'Home' to the TOC if the current page is not the index page - # return - root_doc = app.config.root_doc # Usually 'index' - root_toc = app.env.tocs.get(root_doc) - - if not root_toc: - return - - # Find the outermost bullet_list node - outer_bullet_list = next((n for n in root_toc if isinstance(n, nodes.bullet_list)), None) - if not outer_bullet_list: - return - - # Create a new list_item node for Home - home_item = nodes.list_item() - para = nodes.paragraph() - ref = nodes.reference( - internal=True, - refuri=app.builder.get_relative_uri(pagename, app.config.master_doc), - ) - ref += nodes.Text("🏠 Home") - para += ref - home_item += para - - # Insert Home at the top of the bullet list - outer_bullet_list.insert(0, home_item) - - # Update the doctree in env - app.env.tocs[root_doc] = root_toc - # original_toctree = context.get("toctree") - # import json - # JSON_FILE = pathlib.Path("toctree.json") - # if JSON_FILE.exists(): - # with JSON_FILE.open("r", encoding="utf-8") as f: - # context = json.load(f) - # else: - # with JSON_FILE.open("w", encoding="utf-8") as f: - # json.dump(context, f, indent=2, default=str) - - # if not original_toctree: - # warnings.warn( - # "The 'toctree' function is not available in the context. " - # "This may cause issues with the 'Home' link in the table of contents.", - # UserWarning, - # ) - # exit(1) - # exit(1) - - -# original_toctree = context.get("toctree") - -# if not callable(original_toctree): -# print(original_toctree) -# print("here=========original_toctree is not callable") -# exit(1) -# return # Nothing to patch - -# def new_toctree(*args, **kwargs): -# # Render the normal toctree -# html = original_toctree(*args, **kwargs) - - -# # Create the Home link HTML -# home_url = app.builder.get_relative_uri(pagename, app.config.master_doc) -# home_html = f""" -# -# """ -# print("home_html", home_html) -# return home_html + html - -# # return html # Don't modify other kinds of toctree (e.g. in page content) - -# context["toctree"] = new_toctree - - def traverse_or_findall(node: Node, condition: Union[Callable, type], **kwargs) -> Iterable[Node]: """Triage node.traverse (docutils <0.18.1) vs node.findall. @@ -683,7 +580,6 @@ def setup(app: Sphinx) -> Dict: 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("html-page-context", add_home_to_toc, priority=600) app.connect("doctree-resolved", on_doctree_resolved) app.connect("build-finished", replace_html_tag) From b70964e48ac242cd9fcc071c2bc4f550e15f9592 Mon Sep 17 00:00:00 2001 From: Revathyvenugopal162 Date: Wed, 6 Aug 2025 10:08:09 +0200 Subject: [PATCH 07/16] fix: cleanup the docresolve --- src/ansys_sphinx_theme/__init__.py | 38 +++++++----------------------- 1 file changed, 8 insertions(+), 30 deletions(-) diff --git a/src/ansys_sphinx_theme/__init__.py b/src/ansys_sphinx_theme/__init__.py index 26bb2ef1b..c147bf75a 100644 --- a/src/ansys_sphinx_theme/__init__.py +++ b/src/ansys_sphinx_theme/__init__.py @@ -490,47 +490,25 @@ def traverse_or_findall(node: Node, condition: Union[Callable, type], **kwargs) def on_doctree_resolved(app: Sphinx, doctree: nodes.document, docname: str) -> None: + """Add a 'Package Home' entry to the root TOC.""" + index_page = "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"): - # No entries in the TOC, nothing to do return - # Check if 'Home' already exists in the TOC + for title, page in toc.attributes["entries"]: - # add home, self to the beginning of the TOC - if title == "Home" and page == docname: - # Home already exists, no need to add it again + if title == "Package Home": + # 'Package Home' already exists, no need to add it again return - # if not title == "Home" and page == docname: + home_entry = ( - nodes.Text("🏠 Home"), - app.builder.get_relative_uri(docname, app.config.master_doc), + nodes.Text("Package Home"), + index_page if index_page != docname else None, ) # Insert 'Home' at the beginning of the TOC entries toc.attributes["entries"].insert(0, home_entry) - # # Find the top-level bullet list in the doctree - # outer_bullet_list = next((n for n in root_toc if isinstance(n, nodes.bullet_list)), None) - # if not outer_bullet_list: - # return - - # # Create a new list_item node for Home - # home_item = nodes.list_item() - # para = nodes.paragraph() - # ref = nodes.reference( - # internal=True, - # refuri=app.builder.get_relative_uri(docname, app.config.master_doc), - # ) - # ref += nodes.Text("🏠 Home") - # para += ref - # home_item += para - - # # Insert Home at the top of the bullet list - # outer_bullet_list.insert(0, home_item) - - # # Update the doctree in env - # app.env.tocs[root_doc] = root_toc - def setup(app: Sphinx) -> Dict: """Connect to the Sphinx theme app. From 51c4aa3b4f5c911c4cf7249dd02e1cf116ec5309 Mon Sep 17 00:00:00 2001 From: Revathyvenugopal162 Date: Wed, 6 Aug 2025 10:15:00 +0200 Subject: [PATCH 08/16] fix: strict logo link --- src/ansys_sphinx_theme/__init__.py | 27 ++++++++++++++++++++++----- 1 file changed, 22 insertions(+), 5 deletions(-) diff --git a/src/ansys_sphinx_theme/__init__.py b/src/ansys_sphinx_theme/__init__.py index c147bf75a..1d317534a 100644 --- a/src/ansys_sphinx_theme/__init__.py +++ b/src/ansys_sphinx_theme/__init__.py @@ -382,10 +382,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 @@ -490,7 +492,23 @@ def traverse_or_findall(node: Node, condition: Union[Callable, type], **kwargs) def on_doctree_resolved(app: Sphinx, doctree: nodes.document, docname: str) -> None: - """Add a 'Package Home' entry to the root TOC.""" + """Add a 'Package 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 'Package Home' entry already exists in the root TOC. + If it does not exist, it adds the 'Package Home' entry at the beginning of the TOC. + The 'Package Home' entry links to the index page of the documentation. + """ index_page = "index" root_toc = app.env.tocs[app.config.root_doc] for toc in traverse_or_findall(root_toc, toctree): @@ -499,14 +517,13 @@ def on_doctree_resolved(app: Sphinx, doctree: nodes.document, docname: str) -> N for title, page in toc.attributes["entries"]: if title == "Package Home": - # 'Package Home' already exists, no need to add it again return home_entry = ( nodes.Text("Package Home"), index_page if index_page != docname else None, ) - # Insert 'Home' at the beginning of the TOC entries + # Insert 'Package Home' entry at the beginning of the TOC toc.attributes["entries"].insert(0, home_entry) From 7fb8c857540f3bc04331b5302c8686b7b0900650 Mon Sep 17 00:00:00 2001 From: Revathyvenugopal162 Date: Wed, 6 Aug 2025 10:15:21 +0200 Subject: [PATCH 09/16] fix: precommit --- src/ansys_sphinx_theme/__init__.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/ansys_sphinx_theme/__init__.py b/src/ansys_sphinx_theme/__init__.py index 1d317534a..082ebf6c6 100644 --- a/src/ansys_sphinx_theme/__init__.py +++ b/src/ansys_sphinx_theme/__init__.py @@ -383,7 +383,7 @@ def configure_theme_logo(app: Sphinx): if logo_option == "ansys": theme_options["logo"] = ansys_logo # Ansys logo should link to the ANSYS homepage - theme_options["logo_link"] = ANSYS_LOGO_LINK + theme_options["logo_link"] = ANSYS_LOGO_LINK elif logo_option == "pyansys": theme_options["logo"] = pyansys_logo # PyAnsys logo should link to the PyAnsys Meta documentation @@ -493,7 +493,7 @@ def traverse_or_findall(node: Node, condition: Union[Callable, type], **kwargs) def on_doctree_resolved(app: Sphinx, doctree: nodes.document, docname: str) -> None: """Add a 'Package Home' entry to the root TOC. - + Parameters ---------- app : Sphinx @@ -502,7 +502,7 @@ def on_doctree_resolved(app: Sphinx, doctree: nodes.document, docname: str) -> N Document tree for the page. docname : str Name of the current document. - + Notes ----- This function checks if the 'Package Home' entry already exists in the root TOC. From dddae72fa909a9fd87edb745c19c602b7c74411f Mon Sep 17 00:00:00 2001 From: Revathyvenugopal162 Date: Wed, 6 Aug 2025 10:24:25 +0200 Subject: [PATCH 10/16] fix: update any --- src/ansys_sphinx_theme/__init__.py | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/src/ansys_sphinx_theme/__init__.py b/src/ansys_sphinx_theme/__init__.py index 082ebf6c6..ead7afc59 100644 --- a/src/ansys_sphinx_theme/__init__.py +++ b/src/ansys_sphinx_theme/__init__.py @@ -24,8 +24,7 @@ import os import pathlib -from typing import Any, Callable, Dict, Iterable, Union -import warnings +from typing import Any, Callable, Iterable from docutils import nodes from docutils.nodes import Node @@ -292,7 +291,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. @@ -478,7 +477,7 @@ def update_search_sidebar_context( context["sidebars"] = sidebar -def traverse_or_findall(node: Node, condition: Union[Callable, type], **kwargs) -> Iterable[Node]: +def traverse_or_findall(node: Node, condition: Callable | type, **kwargs) -> Iterable[Node]: """Triage node.traverse (docutils <0.18.1) vs node.findall. TODO: This check can be removed when the minimum supported docutils version @@ -527,7 +526,7 @@ def on_doctree_resolved(app: Sphinx, doctree: nodes.document, docname: str) -> N toc.attributes["entries"].insert(0, home_entry) -def setup(app: Sphinx) -> Dict: +def setup(app: Sphinx) -> dict: """Connect to the Sphinx theme app. Parameters From 5cc571b1f6007151aef5c0e58aff6509cc7df0c2 Mon Sep 17 00:00:00 2001 From: Revathyvenugopal162 Date: Wed, 6 Aug 2025 11:44:35 +0200 Subject: [PATCH 11/16] fix: update the check --- src/ansys_sphinx_theme/__init__.py | 17 ++--------------- 1 file changed, 2 insertions(+), 15 deletions(-) diff --git a/src/ansys_sphinx_theme/__init__.py b/src/ansys_sphinx_theme/__init__.py index ead7afc59..7f907a717 100644 --- a/src/ansys_sphinx_theme/__init__.py +++ b/src/ansys_sphinx_theme/__init__.py @@ -24,10 +24,9 @@ import os import pathlib -from typing import Any, Callable, Iterable +from typing import Any from docutils import nodes -from docutils.nodes import Node from sphinx import addnodes from sphinx.addnodes import toctree from sphinx.application import Sphinx @@ -41,6 +40,7 @@ create_search_index, update_search_config, ) +from pydata_sphinx_theme.toctree import traverse_or_findall from ansys_sphinx_theme.whatsnew import ( add_whatsnew_changelog, extract_whatsnew, @@ -477,19 +477,6 @@ def update_search_sidebar_context( context["sidebars"] = sidebar -def traverse_or_findall(node: Node, condition: Callable | type, **kwargs) -> Iterable[Node]: - """Triage node.traverse (docutils <0.18.1) vs node.findall. - - TODO: This check can be removed when the minimum supported docutils version - for numpydoc is docutils>=0.18.1. - """ - return ( - node.findall(condition, **kwargs) - if hasattr(node, "findall") - else node.traverse(condition, **kwargs) - ) - - def on_doctree_resolved(app: Sphinx, doctree: nodes.document, docname: str) -> None: """Add a 'Package Home' entry to the root TOC. From ec08c2cf046e83211a74db049e512454027fc55b Mon Sep 17 00:00:00 2001 From: Revathyvenugopal162 Date: Wed, 6 Aug 2025 14:39:30 +0200 Subject: [PATCH 12/16] fix: update pre-commit --- src/ansys_sphinx_theme/__init__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/ansys_sphinx_theme/__init__.py b/src/ansys_sphinx_theme/__init__.py index 7f907a717..f31c7fc21 100644 --- a/src/ansys_sphinx_theme/__init__.py +++ b/src/ansys_sphinx_theme/__init__.py @@ -27,6 +27,7 @@ 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 @@ -40,7 +41,6 @@ create_search_index, update_search_config, ) -from pydata_sphinx_theme.toctree import traverse_or_findall from ansys_sphinx_theme.whatsnew import ( add_whatsnew_changelog, extract_whatsnew, From e458be153b67ec16abe66d97bb74501e31a38866 Mon Sep 17 00:00:00 2001 From: pyansys-ci-bot <92810346+pyansys-ci-bot@users.noreply.github.com> Date: Tue, 12 Aug 2025 12:32:47 +0000 Subject: [PATCH 13/16] chore: adding changelog file 769.fixed.md [dependabot-skip] --- doc/changelog.d/769.fixed.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/changelog.d/769.fixed.md b/doc/changelog.d/769.fixed.md index 12687fca1..a84b9838a 100644 --- a/doc/changelog.d/769.fixed.md +++ b/doc/changelog.d/769.fixed.md @@ -1 +1 @@ -Add home section \ No newline at end of file +Add home section From ed462dfb927d72b259c3c8c859bb96d322b2008a Mon Sep 17 00:00:00 2001 From: Revathyvenugopal162 Date: Thu, 14 Aug 2025 09:52:47 +0200 Subject: [PATCH 14/16] feat: add tooltip --- src/ansys_sphinx_theme/__init__.py | 51 +++++++++++++++++++++++++----- 1 file changed, 43 insertions(+), 8 deletions(-) diff --git a/src/ansys_sphinx_theme/__init__.py b/src/ansys_sphinx_theme/__init__.py index f31c7fc21..27a511d8f 100644 --- a/src/ansys_sphinx_theme/__init__.py +++ b/src/ansys_sphinx_theme/__init__.py @@ -32,6 +32,7 @@ from sphinx.addnodes import toctree from sphinx.application import Sphinx from sphinx.util import logging +from bs4 import BeautifulSoup from ansys_sphinx_theme.cheatsheet import build_quarto_cheatsheet, cheatsheet_sidebar_pages from ansys_sphinx_theme.extension.linkcode import DOMAIN_KEYS, sphinx_linkcode_resolve @@ -478,7 +479,7 @@ def update_search_sidebar_context( def on_doctree_resolved(app: Sphinx, doctree: nodes.document, docname: str) -> None: - """Add a 'Package Home' entry to the root TOC. + """Add a 'Home' entry to the root TOC. Parameters ---------- @@ -491,9 +492,9 @@ def on_doctree_resolved(app: Sphinx, doctree: nodes.document, docname: str) -> N Notes ----- - This function checks if the 'Package Home' entry already exists in the root TOC. - If it does not exist, it adds the 'Package Home' entry at the beginning of the TOC. - The 'Package Home' entry links to the index page of the documentation. + 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 = "index" root_toc = app.env.tocs[app.config.root_doc] @@ -502,15 +503,49 @@ def on_doctree_resolved(app: Sphinx, doctree: nodes.document, docname: str) -> N return for title, page in toc.attributes["entries"]: - if title == "Package Home": + if title == "Home": return home_entry = ( - nodes.Text("Package Home"), + nodes.Text("Home"), index_page if index_page != docname else None, ) - # Insert 'Package Home' entry at the beginning of the TOC + # 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 = f"{app.config.html_short_title} home" or None + if not project_name: + project_name = f"{app.config.project} home" or "Package Home" + + for html_file in outdir.rglob("*.html"): + with html_file.open("r", encoding="utf-8") as f: + soup = BeautifulSoup(f, "html.parser") + + for a in soup.find_all("a", string=lambda t: t and "Home" in t): + a['title'] = project_name + + with html_file.open("w", encoding="utf-8") as f: + f.write(str(soup)) def setup(app: Sphinx) -> dict: @@ -555,7 +590,6 @@ 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) @@ -564,6 +598,7 @@ def setup(app: Sphinx) -> dict: 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) From 918dacbb28072b34f1952dc065b135323f5caf82 Mon Sep 17 00:00:00 2001 From: Revathyvenugopal162 Date: Thu, 14 Aug 2025 09:53:13 +0200 Subject: [PATCH 15/16] fix: codestyle --- src/ansys_sphinx_theme/__init__.py | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/src/ansys_sphinx_theme/__init__.py b/src/ansys_sphinx_theme/__init__.py index 27a511d8f..e1261964c 100644 --- a/src/ansys_sphinx_theme/__init__.py +++ b/src/ansys_sphinx_theme/__init__.py @@ -26,13 +26,13 @@ import pathlib from typing import Any +from bs4 import BeautifulSoup 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 -from bs4 import BeautifulSoup from ansys_sphinx_theme.cheatsheet import build_quarto_cheatsheet, cheatsheet_sidebar_pages from ansys_sphinx_theme.extension.linkcode import DOMAIN_KEYS, sphinx_linkcode_resolve @@ -512,8 +512,7 @@ def on_doctree_resolved(app: Sphinx, doctree: nodes.document, docname: str) -> N ) # 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. @@ -530,7 +529,7 @@ def add_tooltip_after_build(app: Sphinx, exception): None """ if exception: - return + return outdir = pathlib.Path(app.outdir) project_name = f"{app.config.html_short_title} home" or None @@ -542,7 +541,7 @@ def add_tooltip_after_build(app: Sphinx, exception): soup = BeautifulSoup(f, "html.parser") for a in soup.find_all("a", string=lambda t: t and "Home" in t): - a['title'] = project_name + a["title"] = project_name with html_file.open("w", encoding="utf-8") as f: f.write(str(soup)) From 945e5a65e8d5c87c9d894a6de41f17437e5c96ed Mon Sep 17 00:00:00 2001 From: Revathyvenugopal162 Date: Thu, 14 Aug 2025 10:03:05 +0200 Subject: [PATCH 16/16] fix: depedencies --- pyproject.toml | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 579a636ca..31fde05c7 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -30,25 +30,26 @@ classifiers = [ "Programming Language :: Python :: 3.13", ] dependencies = [ - "Sphinx>=6.1.0", - "pydata-sphinx-theme>=0.15.4,<0.17", - "Jinja2>=3.1.2", + "beautifulsoup4==4.13.4", "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.1", "Pillow>=9.0", @@ -63,8 +64,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",