Merge pull request #358 from samjwu/common-404

feat: copy common 404.md source file to projects' docs folder

src/rocm_docs/data/util_pages/404.md

@@ -0,0 +1,7 @@
+# 404 - Page Not Found
+
+```{figure} ./data/AMD-404.png
+:align: center
+```
+
+Return [home](./index) or use the sidebar navigation to get back on track.

src/rocm_docs/doxygen.py

@@ -16,56 +16,27 @@
 from sphinx.config import Config
 from sphinx.errors import ConfigError
 
+from rocm_docs import util
+
 if sys.version_info < (3, 9):
     # importlib.resources either doesn't exist or lacks the files()
     # function, so use the PyPI version:
     import importlib_resources
-    from importlib_resources.abc import Traversable
 else:
     # importlib.resources has files(), so use that:
     import importlib.resources as importlib_resources
 
-    if sys.version_info < (3, 11):
-        from importlib.abc import Traversable
-    else:
-        from importlib.resources.abc import Traversable
-
 
 def _copy_files(app: Sphinx) -> None:
     """Insert additional files into workspace."""
-
-    def copy_from_package(
-        data_dir: Traversable, read_path: str, write_path: str
-    ) -> None:
-        if not data_dir.is_dir():
-            raise NotADirectoryError(
-                f"Expected path {read_path}/{data_dir} to be traversable."
-            )
-        for entry in data_dir.iterdir():
-            entry_path: Path = Path(app.confdir) / write_path / entry.name
-            if entry.is_dir():
-                entry_path.mkdir(parents=True, exist_ok=True)
-                copy_from_package(
-                    entry,
-                    read_path + "/" + entry.name,
-                    write_path + "/" + entry.name,
-                )
-            else:
-                # We open the resource file as a binary stream instead
-                # of a file on disk because the latter may require
-                # unzipping and/or the creation of a temporary file.
-                # This is not the case when opening the file as a
-                # stream.
-                with entry.open("rb") as infile:
-                    with open(entry_path, "wb") as out:
-                        shutil.copyfileobj(infile, out)
-
     pkg = importlib_resources.files("rocm_docs")
     try:
         Path(app.confdir, "_doxygen").mkdir()
     except FileExistsError:
         pass
-    copy_from_package(pkg / "data/_doxygen", "data/_doxygen", "_doxygen")
+    util.copy_from_package(
+        app, pkg / "data/_doxygen", "data/_doxygen", "_doxygen"
+    )
 
 
 def _get_config_default(config: Config, key: str) -> Any:

src/rocm_docs/theme.py

@@ -2,6 +2,7 @@
 
 from typing import Any, Dict
 
+import sys
 from pathlib import Path
 
 import sphinx.util.logging
@@ -13,9 +14,23 @@
 
 from rocm_docs import util
 
+if sys.version_info < (3, 9):
+    # importlib.resources either doesn't exist or lacks the files()
+    # function, so use the PyPI version:
+    import importlib_resources
+else:
+    # importlib.resources has files(), so use that:
+    import importlib.resources as importlib_resources
+
 logger = sphinx.util.logging.getLogger(__name__)
 
 
+def _copy_theme_util_pages(app: Sphinx) -> None:
+    """Copy over common utility pages before generating docs."""
+    pkg = importlib_resources.files("rocm_docs")
+    util.copy_from_package(app, pkg / "data/util_pages", "data/util_pages", ".")
+
+
 def _update_repo_opts(
     srcdir: str, url: str, branch: str, theme_opts: Dict[str, Any]
 ) -> None:
@@ -111,6 +126,8 @@ def setup(app: Sphinx) -> Dict[str, Any]:
         "fonts.css",
     ]:
         app.add_css_file(css)
+
+    app.connect("builder-inited", _copy_theme_util_pages, priority=400)
     app.connect("builder-inited", _update_theme_options)
 
     return {

src/rocm_docs/util.py

@@ -8,11 +8,22 @@
 import functools
 import os
 import re
+import shutil
+import sys
 from pathlib import Path
 
 import github
 from git.repo import Repo
 from github.GithubException import UnknownObjectException
+from sphinx.application import Sphinx
+
+if sys.version_info < (3, 9):
+    from importlib_resources.abc import Traversable
+else:
+    if sys.version_info < (3, 11):
+        from importlib.abc import Traversable
+    else:
+        from importlib.resources.abc import Traversable
 
 
 class VersionType(enum.Enum):
@@ -117,3 +128,32 @@ def get_repo_url(remote_url: str) -> str:
         branch = "branch-not-found"
 
     return "", branch
+
+
+def copy_from_package(
+    app: Sphinx, data_dir: Traversable, read_path: str, write_path: str
+) -> None:
+    """Copy files from package specified in data_dir."""
+    if not data_dir.is_dir():
+        raise NotADirectoryError(
+            f"Expected path {read_path}/{data_dir} to be traversable."
+        )
+    for entry in data_dir.iterdir():
+        entry_path: Path = Path(app.confdir) / write_path / entry.name
+        if entry.is_dir():
+            entry_path.mkdir(parents=True, exist_ok=True)
+            copy_from_package(
+                app,
+                entry,
+                read_path + "/" + entry.name,
+                write_path + "/" + entry.name,
+            )
+        else:
+            # We open the resource file as a binary stream instead
+            # of a file on disk because the latter may require
+            # unzipping and/or the creation of a temporary file.
+            # This is not the case when opening the file as a
+            # stream.
+            with entry.open("rb") as infile:
+                with open(entry_path, "wb") as out:
+                    shutil.copyfileobj(infile, out)