Move theme options to a custom sphinx theme

docs/.gitignore

@@ -1,5 +1,2 @@
 /_build
 /_doxygen
-/_images
-/_static
-/_templates

pyproject.toml

@@ -30,3 +30,6 @@ requires-python = ">=3.8"
 api_reference = [
   "doxysphinx>=3.2.1,<4"
 ]
+
+[project.entry-points."sphinx.html_themes"]
+rocm_docs_theme = "rocm_docs.theme"

src/rocm_docs/__init__.py

@@ -43,15 +43,10 @@ class ROCmDocs:
         "external_toc_exclude_missing",
         "intersphinx_mapping",
         "intersphinx_disabled_domains",
-        "templates_path",
         "epub_show_urls",
         "exclude_patterns",
         "html_theme",
         "html_title",
-        "html_static_path",
-        "html_css_files",
-        "html_js_files",
-        "html_extra_path",
         "html_theme_options",
         "html_show_sphinx",
         "html_favicon",
@@ -80,11 +75,7 @@ def __init__(
         self.exclude_patterns: List[str]
         self.html_theme: str
         self.html_title: str
-        self.html_static_path: List[str]
-        self.html_css_files: List[str]
-        self.html_js_files: List[str]
-        self.html_extra_path: List[str]
-        self.html_theme_options: Dict[str, Union[str, bool, List[str]]]
+        self.html_theme_options: Dict[str, Union[str, bool, List[str]]] = {}
         self.html_show_sphinx: bool
         self.html_favicon: str
         self.numfig: bool
@@ -269,7 +260,6 @@ def setup(self) -> None:
                 " readable."
             )
         format_toc(self._docs_folder)
-        url, branch, edit_page = get_branch(self._docs_folder)
 
         self.external_toc_path = "./.sphinx/_toc.yml"
         self.external_toc_exclude_missing = False
@@ -282,9 +272,6 @@ def setup(self) -> None:
         }
         self.intersphinx_disabled_domains = ["std"]
 
-        # Other configuration
-        self.templates_path = ["_templates"]
-
         # -- Options foself.r EPUB output
         self.epub_show_urls = "footnote"
 
@@ -298,32 +285,8 @@ def setup(self) -> None:
         # The theme to use for HTML and HTML Help pages.  See the documentation
         # for a list of builtin themes.
         #
-        self.html_theme = "sphinx_book_theme"
+        self.html_theme = "rocm_docs_theme"
         self.html_title = self._project_name
-        self.html_static_path = ["_static"]
-        self.html_css_files = [
-            "custom.css",
-            "rocm_header.css",
-            "rocm_footer.css",
-            "fonts.css",
-        ]
-        self.html_js_files = ["code_word_breaks.js"]
-        self.html_extra_path = ["_images"]
-        self.html_theme_options = {
-            "home_page_in_toc": False,
-            "use_edit_page_button": edit_page,
-            "repository_url": url,
-            "repository_branch": branch,
-            "path_to_docs": get_path_to_docs(),
-            "show_navbar_depth": "0",
-            "body_max_width": "none",
-            "show_toc_level": "0",
-            "article_header_start": [
-                "toggle-primary-sidebar.html",
-                "breadcrumbs.html",
-            ],
-            "navbar_center": ["components/left-side-menu.html"],
-        }
 
         self.html_show_sphinx = False
         self.html_favicon = "https://www.amd.com/themes/custom/amd/favicon.ico"
@@ -333,7 +296,7 @@ def setup(self) -> None:
         self.copy_files()
 
     def disable_main_doc_link(self):
-        self.html_theme_options.pop("navbar_center")
+        self.html_theme_options["link_main_doc"] = False
 
     def copy_files(self):
         """Insert additional files into workspace."""

src/rocm_docs/data/_templates/layout.html → src/rocm_docs/rocm_docs_theme/layout.html

@@ -1,4 +1,4 @@
-{% extends "!layout.html" %}
+{% extends "sphinx_book_theme/layout.html" %}
 
 {%- block footer %}
     {%- include "sections/footer.html" %}

src/rocm_docs/data/_templates/sections/footer.html → src/rocm_docs/rocm_docs_theme/sections/footer.html

@@ -19,5 +19,5 @@
 </div>
 
 <div id="rdc-watermark-container">
-    <img id="rdc-watermark" src="{{ pathto('rdc-watermark.svg',1) }}" alt="DRAFT watermark"/>
+    <img id="rdc-watermark" src="{{ pathto('_static/images/rdc-watermark.svg',1) }}" alt="DRAFT watermark"/>
 </div>

src/rocm_docs/data/_templates/sections/header.html → src/rocm_docs/rocm_docs_theme/sections/header.html

@@ -1,7 +1,7 @@
 <div class="rocm-header">
     <div class="rocm-header-buttons">
         <a href="https://www.amd.com" class="rocm-header-link">
-            <img id="amd-logo" alt="Advanced Micro Devices, Inc." src="{{ pathto('rocm-logo.png',1) }}"></img>
+            <img id="amd-logo" alt="Advanced Micro Devices, Inc." src="{{ pathto('_static/images/rocm-logo.png',1) }}"></img>
             <div class="glow-wrap">
                 <i class="glow"></i>
             </div>

src/rocm_docs/rocm_docs_theme/theme.conf

@@ -0,0 +1,5 @@
+[theme]
+inherit = sphinx_book_theme
+
+[options]
+link_main_doc = True

src/rocm_docs/theme.py

@@ -0,0 +1,42 @@
+import sphinx
+from sphinx.application import Sphinx
+from sphinx.config import Config
+from typing import Dict, Any
+from pathlib import Path
+from pydata_sphinx_theme import _get_theme_options
+import rocm_docs.util as util
+
+def _update_theme_options(app: Sphinx) -> None:
+    url, branch, edit_page = util.get_branch(app.srcdir)
+
+    options = _get_theme_options(app)
+    options.update({
+        "home_page_in_toc": False,
+        "use_edit_page_button": edit_page,
+        "repository_url": url,
+        "repository_branch": branch,
+        "path_to_docs": util.get_path_to_docs(app.srcdir),
+        "show_navbar_depth": "0",
+        "body_max_width": "none",
+        "show_toc_level": "0",
+        "article_header_start": [
+            "toggle-primary-sidebar.html",
+            "breadcrumbs.html",
+        ],
+    })
+    if options.get("link_main_doc", True):
+        options["navbar_center"] = ["components/left-side-menu"]
+
+def setup(app: Sphinx) -> Dict[str, Any]:
+    app.add_js_file("code_word_breaks.js", loading_method="async")
+    here = Path(__file__).parent.resolve()
+    theme_path = here / "rocm_docs_theme"
+    app.add_html_theme("rocm_docs_theme", str(theme_path))
+    for css in ["custom.css", "rocm_header.css", "rocm_footer.css", "fonts.css"]:
+        app.add_css_file(css)
+    app.connect("builder-inited", _update_theme_options)
+
+    return {
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }