From b095b3fab0dba91f7a7f11fa368d88da7e1a1c09 Mon Sep 17 00:00:00 2001
From: Kimberly Meechan <24316371+K-Meech@users.noreply.github.com>
Date: Thu, 11 Apr 2024 11:13:00 +0100
Subject: [PATCH] expand header_widget to include doc path, citation and help
 text

---
 brainglobe_utils/qtpy/logo.py      | 86 ++++++++++++++++++++++++------
 tests/tests/test_qtpy/test_logo.py | 19 +++++--
 2 files changed, 87 insertions(+), 18 deletions(-)

diff --git a/brainglobe_utils/qtpy/logo.py b/brainglobe_utils/qtpy/logo.py
index 78d9d75..91c7ce1 100644
--- a/brainglobe_utils/qtpy/logo.py
+++ b/brainglobe_utils/qtpy/logo.py
@@ -6,18 +6,51 @@
 def _docs_links_widget(
     package_name: str,
     package_tagline: str,
-    tutorial_file_name: str,
+    tutorial_file_name: str = None,
+    documentation_path: str = None,
+    citation_doi: str = None,
+    github_repo_name: str = None,
+    help_text: str = None,
     parent: QWidget = None,
 ):
-    _docs_links_html = f"""
-    <h3>
-    <p>{package_tagline}</p>
-    <p><a href="https://brainglobe.info" style="color:gray;">Website</a></p>
-    <p><a href="https://brainglobe.info/tutorials/{tutorial_file_name}" style="color:gray;">Tutorial</a></p>
-    <p><a href="https://github.com/brainglobe/{package_name}" style="color:gray;">Source</a></p>
-    </h3>
-    """  # noqa: E501
-    docs_links_widget = QLabel(_docs_links_html, parent=parent)
+    lines = [
+        "<h3>",
+        f"<p>{package_tagline}</p>",
+        "<p><a href='https://brainglobe.info' style='color:gray;'>"
+        "Website</a></p>",
+    ]
+
+    if tutorial_file_name:
+        lines.append(
+            f"<p>"
+            f"<a href='https://brainglobe.info/tutorials/{tutorial_file_name}'"
+            f" style='color:gray;'>Tutorial</a></p>"
+        )
+
+    if documentation_path:
+        lines.append(
+            f"<p><a href="
+            f"'https://brainglobe.info/documentation/{documentation_path}' "
+            f"style='color:gray;'>Documentation</a></p>"
+        )
+
+    if github_repo_name is None:
+        github_repo_name = package_name
+    lines.append(
+        f"<p><a href='https://github.com/brainglobe/{github_repo_name}' "
+        f"style='color:gray;'>Source</a></p>"
+    )
+
+    if citation_doi:
+        lines.append(
+            f"<p><a href='{citation_doi}' style='color:gray;'>Citation</a></p>"
+        )
+
+    if help_text:
+        lines.append(f"<p><small>{help_text}</small></p>")
+
+    lines.append("</h3>")
+    docs_links_widget = QLabel("\n".join(lines), parent=parent)
     docs_links_widget.setOpenExternalLinks(True)
     return docs_links_widget
 
@@ -38,9 +71,13 @@ def _logo_widget(package_name: str, parent: QWidget = None):
 def header_widget(
     package_name: str,
     package_tagline: str,
-    tutorial_file_name: str,
+    tutorial_file_name: str = None,
+    documentation_path: str = None,
+    citation_doi: str = None,
+    github_repo_name: str = None,
+    help_text: str = None,
     parent: QWidget = None,
-):
+) -> QGroupBox:
     """
     Render HTML in a QGroupBox with a BrainGlobe logo and links to the docs
      and source code.
@@ -51,9 +88,21 @@ def header_widget(
         The name of the package, e.g. "brainrender-napari"
     package_tagline : str
         The tagline for the package
-    tutorial_file_name : str
+    tutorial_file_name : str, optional
         The name of the tutorial file (must include .html),
-         e.g. "brainrender-qtpy.html": str
+         e.g. "brainrender-qtpy.html"
+    documentation_path : str, optional
+        The relative path of a documentation file (must include .html),
+        e.g. "cellfinder/user-guide/napari-plugin/index.html"
+    citation_doi : str, optional
+        Doi of citation e.g. "https://doi.org/10.1371/journal.pcbi.1009074"
+    github_repo_name : str, optional
+        Name of github repository inside the BrainGlobe organisation
+        (https://github.com/brainglobe). Only necessary if the github
+        repository name isn't the same as the package name.
+    help_text : str, optional
+        Help text to display at the bottom or the header e.g.
+        "For help, hover the cursor over each parameter."
     parent : QWidget
         The parent widget, defaults to None
 
@@ -69,7 +118,14 @@ def header_widget(
     box.layout().addWidget(_logo_widget(package_name, parent=box))
     box.layout().addWidget(
         _docs_links_widget(
-            package_name, package_tagline, tutorial_file_name, parent=box
+            package_name,
+            package_tagline,
+            tutorial_file_name,
+            documentation_path,
+            citation_doi,
+            github_repo_name,
+            help_text,
+            parent=box,
         )
     )
 
diff --git a/tests/tests/test_qtpy/test_logo.py b/tests/tests/test_qtpy/test_logo.py
index e1134be..0e7eb88 100644
--- a/tests/tests/test_qtpy/test_logo.py
+++ b/tests/tests/test_qtpy/test_logo.py
@@ -4,16 +4,29 @@
 def test_logo(qtbot):
     package_name = "test"
     package_tagline = "Tagline"
-    package_tutorial = "test.html"
+    tutorial_file_name = "test-tutorial.html"
+    documentation_path = "test-docs/test.html"
+    citation_doi = "https://doi.org/test"
+    help_text = "For help, hover the cursor over each parameter."
 
-    header = header_widget(package_name, package_tagline, package_tutorial)
+    header = header_widget(
+        package_name,
+        package_tagline,
+        tutorial_file_name=tutorial_file_name,
+        documentation_path=documentation_path,
+        citation_doi=citation_doi,
+        help_text=help_text,
+    )
 
     qtbot.addWidget(header)
 
     expected_strings_logo = [package_name, "brainglobe.png"]
     expected_strings_docs = [
         package_tagline,
-        package_tutorial,
+        tutorial_file_name,
+        documentation_path,
+        citation_doi,
+        help_text,
         "https://brainglobe.info",
         "https://github.com",
     ]