FEAT: update theme to latest pydata-sphinx-theme layout (#190)

* MAINT: move breadcrumbs.html to components/ dir

* MAINT: collect examples under a common sub-package

* MAINT: remove docs-navbar.html

* MAINT: move icon-links.html to components/

* FIX: explicit conditionals in layout.html for announcement

* FEAT: apply theme structure

* FIX: theme variable name

Co-authored-by: Revathy Venugopal <104772255+Revathyvenugopal162@users.noreply.github.com>

* resolve style error

* FIX: remove unused section

* FEAT: add default configuration

* Remove unused section

* Resolves code style error

* FEAT: add default HTML options

* FIX: remove blank line in theme.conf

* FIX: remove unused html_logo variable

Co-authored-by: Revathy Venugopal <104772255+Revathyvenugopal162@users.noreply.github.com>

---------

Co-authored-by: Revathy Venugopal <104772255+Revathyvenugopal162@users.noreply.github.com>
Co-authored-by: Revathyvenugopal162 <revathy.venugopal@ansys.com>

doc/source/conf.py

@@ -22,7 +22,7 @@
 # Project information
 project = "ansys_sphinx_theme"
 copyright = f"(c) {datetime.now().year} ANSYS, Inc. All rights reserved"
-author = "Ansys Inc."
+author = "ANSYS, Inc."
 release = version = __version__
 cname = os.getenv("DOCUMENTATION_CNAME", "nocname.com")
 
@@ -40,7 +40,6 @@
 # specify the location of your github repo
 html_theme_options = {
     "github_url": "https://github.com/ansys/ansys-sphinx-theme",
-    "use_edit_page_button": True,
     "contact_mail": "pyansys.support@ansys.com",
     "additional_breadcrumbs": [
         ("Ansys Internal Developer Portal", "https://dev.docs.ansys.com"),
@@ -55,7 +54,6 @@
         "json_url": f"https://{cname}/release/versions.json",
         "version_match": get_version_match(__version__),
     },
-    "navbar_end": ["version-switcher", "theme-switcher", "navbar-icon-links"],
 }
 
 html_short_title = html_title = "Ansys Sphinx Theme"

pyproject.toml

@@ -46,12 +46,11 @@ name = "ansys_sphinx_theme"
 
 [tool.flit.sdist]
 include = [
-    "src/ansys_sphinx_theme/layout.html",
-    "src/ansys_sphinx_theme/breadcrumbs.html",
-    "src/ansys_sphinx_theme/docs-navbar.html",
-    "src/ansys_sphinx_theme/theme.conf",
-    "src/ansys_sphinx_theme/_templates/",
-    "src/ansys_sphinx_theme/static/",
+    "src/ansys_sphinx_theme/theme/ansys_sphinx_theme/layout.html",
+    "src/ansys_sphinx_theme/theme/ansys_sphinx_theme/components/breadcrumbs.html",
+    "src/ansys_sphinx_theme/theme/ansys_sphinx_theme/theme.conf",
+    "src/ansys_sphinx_theme/theme/ansys_sphinx_theme/_templates/",
+    "src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/",
 ]
 
 [project.urls]

src/ansys_sphinx_theme/__init__.py

@@ -1,55 +1,115 @@
 """This is the ansys-sphinx-theme module."""
-import os
-from pathlib import Path
+import pathlib
+from typing import Dict
+
+import sphinx
 
 from ansys_sphinx_theme.latex import generate_404  # noqa: F401
 
 __version__ = "0.9.dev0"
 
-# get location of this directory
-_this_path = os.path.dirname(os.path.realpath(__file__))
+
+# Declare the fundamental paths of the theme
+THIS_PATH = pathlib.Path(__file__).parent.resolve()
+THEME_PATH = THIS_PATH / "theme" / "ansys_sphinx_theme"
+STATIC_PATH = THEME_PATH / "static"
+STYLE_PATH = STATIC_PATH / "css"
+CSS_PATH = STYLE_PATH / "ansys_sphinx_theme.css"
+TEMPLATES_PATH = THEME_PATH / "_templates"
 
 # make logo paths available
-pyansys_logo_black = os.path.join(_this_path, "static", "pyansys-logo-black-cropped.png")
-pyansys_logo_white = os.path.join(_this_path, "static", "pyansys-logo-white-cropped.png")
-ansys_favicon = os.path.join(_this_path, "static", "ansys-favicon.png")
-ansys_logo_white = os.path.join(_this_path, "static", "ansys_logo_white.pdf")
-ansys_logo_white_cropped = os.path.join(_this_path, "static", "ansys_logo_white_cropped.pdf")
-watermark = os.path.join(_this_path, "static", "watermark.pdf")
-ansys_logo_black = os.path.join(_this_path, "static", "ansys_logo_black_cropped.jpg")
+ansys_favicon = str((STATIC_PATH / "ansys-favicon.png").absolute())
+ansys_logo_black = str((STATIC_PATH / "ansys_logo_black_cropped.jpg").absolute())
+ansys_logo_white = str((STATIC_PATH / "ansys_logo_white.pdf").absolute())
+ansys_logo_white_cropped = str((STATIC_PATH / "ansys_logo_white_cropped.pdf").absolute())
+page_404 = str((STATIC_PATH / "404.rst").absolute())
+pyansys_logo_black = str((STATIC_PATH / "pyansys-logo-black-cropped.png").absolute())
+pyansys_logo_white = str((STATIC_PATH / "pyansys-logo-white-cropped.png").absolute())
+watermark = str((STATIC_PATH / "watermark.pdf").absolute())
+
+
+def get_html_theme_path() -> pathlib.Path:
+    """Return list of HTML theme paths.
 
-# Enable default 404 page
-page_404 = os.path.join(_this_path, "static", "404.rst")
+    Returns
+    -------
+    pathlib.Path
+        Path pointing to the installation directory of the theme.
 
-html_logo = pyansys_logo_black
-CSS_FILENAME = "ansys_sphinx_theme.css"
+    """
+    return THEME_PATH.resolve()
 
 
-def get_html_theme_path():
-    """Return list of HTML theme paths."""
-    return Path(__file__).parents[0].absolute()
+def get_version_match(semver: str) -> str:
+    """Evaluate the version match for the multi-documentation.
 
+    Parameters
+    ----------
+    semver : str
+        Semantic version number in the form of a string.
 
-def get_version_match(semver):
-    """Evaluate the version match for the multi-documentation."""
+    Returns
+    -------
+    str
+        Matching version number in the form of a string.
+
+    """
     if semver.endswith("dev0"):
         return "dev"
     major, minor, _ = semver.split(".")
     return ".".join([major, minor])
 
 
-def setup(app):
-    """Connect to the sphinx theme app."""
+def setup_default_html_theme_options(app):
+    """Set up the default configuration for the HTML options.
+
+    Parameters
+    ----------
+    app : sphinx.application.Sphinx
+        Application instance for rendering the documentation.
+
+    Notes
+    -----
+    This function is the only way to overwrite ``pydata-sphinx-theme``
+    configuration. Variables declared in the ``theme.conf`` do not include
+    inherited ones.
+
+    """
+    # Place all switchers and icons at the end of the navigation bar
+    app.config.html_theme_options.setdefault(
+        "navbar_end", ["version-switcher", "theme-switcher", "navbar-icon-links"]
+    )
+
+
+def setup(app: sphinx.application.Sphinx) -> Dict:
+    """Connect to the sphinx theme app.
+
+    Parameters
+    ----------
+    app : sphinx.application.Sphinx
+        Application instance for rendering the documentation.
+
+    Returns
+    -------
+    Dict
+        Dictionary containing application status.
+
+    """
+    # Add the theme configuration
     theme_path = get_html_theme_path()
     app.add_html_theme("ansys_sphinx_theme", theme_path)
-    theme_css_path = theme_path / "static" / "css" / CSS_FILENAME
-    if not theme_css_path.exists():
-        raise FileNotFoundError(f"Unable to locate ansys-sphinx theme at {theme_css_path}")
-    app.add_css_file(str(theme_css_path.relative_to(theme_path / "static")))
-
-    # add templates for autosummary
-    path_templates = os.path.join(_this_path, "_templates")
-    app.config.templates_path.append(path_templates)
+    app.config.templates_path.append(str(THEME_PATH / "components"))
+
+    # Add default HTML configuration
+    setup_default_html_theme_options(app)
+
+    # Verify that the main CSS file exists
+    if not CSS_PATH.exists():
+        raise FileNotFoundError(f"Unable to locate ansys-sphinx theme at {CSS_PATH.absolute()}")
+    app.add_css_file(str(CSS_PATH.relative_to(STATIC_PATH)))
+
+    # Add templates for autosummary
+    app.config.templates_path.append(str(TEMPLATES_PATH))
 
     return {
         "version": __version__,

src/ansys_sphinx_theme/examples/__init__.py

@@ -0,0 +1 @@
+"""A sub-package containing various examples for checking their rendering."""

src/ansys_sphinx_theme/announcement_layout.html → src/ansys_sphinx_theme/theme/ansys_sphinx_theme/components/announcement_version.html

@@ -1,4 +1,3 @@
-{% if theme_switcher %} 
 <div id="announcement_msg"></div>
 <script>
   fetch("announcement.html")
@@ -11,4 +10,3 @@
     .then(text => document.getElementById("announcement_msg").innerHTML = text)
     .catch((error) => console.error(`Fetch problem: ${error.message}`));
 </script>
-{% endif %}

src/ansys_sphinx_theme/layout.html → src/ansys_sphinx_theme/theme/ansys_sphinx_theme/layout.html

@@ -26,9 +26,12 @@
 
 {% block docs_navbar %}
     {{ super() }}
-    {% include 'announcement_layout.html' %}
+
+    {% if theme_switcher %}
+    {% include 'components/announcement_version.html' %}
+    {% endif %}
+
     {% if theme_show_breadcrumbs %}
-        {% include 'breadcrumbs.html' %}
+    {% include 'components/breadcrumbs.html' %}
     {% endif %}
 {% endblock %}
-

src/ansys_sphinx_theme/theme.conf → src/ansys_sphinx_theme/theme/ansys_sphinx_theme/theme.conf

@@ -10,4 +10,5 @@ show_breadcrumbs = True
 show_icons = True
 hidden_icons =
 additional_breadcrumbs =
-switcher =
+use_edit_page_button = True
+switcher =