Improve support for external theme packages by using a get_scss_sources_path() convention

Author: jdillard

docs/changelog.rst

@@ -1,6 +1,12 @@
 Changelog
 =========
 
+Release 1.8
+-----------
+:released: unreleased
+
+* **Bugfix**: Improve support for external theme packages by using a ``get_scss_sources_path()`` convention.
+
 Release 1.7
 -----------
 :released: 02.12.2025

docs/configuration.rst

@@ -166,7 +166,41 @@ simplepdf_theme
 ---------------
 .. versionadded:: 1.5
 
-Add custom theme for simplepdf. This overrides the default theme ``simplepdf_theme``
+Name of the theme to use for PDF output. This overrides the default theme ``simplepdf_theme``.
+The value must match both the Sphinx theme name and the importable Python module name.
+
+.. code-block:: python
+
+   simplepdf_theme = "my_custom_pdf_theme"
+
+Using an external theme
+~~~~~~~~~~~~~~~~~~~~~~~
+External themes are installed as separate Python packages that provide their own
+SCSS sources for PDF styling. To use one:
+
+1. Install the theme package (e.g. ``pip install my-custom-pdf-theme``).
+2. Set ``simplepdf_theme`` in your ``conf.py`` to the theme's module name.
+
+The theme module must define a ``get_scss_sources_path()`` function that returns
+the absolute path to its SCSS sources directory. This is how the builder locates
+the SCSS files to compile into CSS for the PDF.
+
+**Minimal example:**
+
+.. code-block:: python
+
+   from os import path
+
+   def get_scss_sources_path():
+       """Return the absolute path to the SCSS sources directory."""
+       return path.join(path.abspath(path.dirname(__file__)), "static", "styles", "sources")
+
+The SCSS sources directory should contain a ``main.scss`` file as the entry point.
+You can use the bundled ``simplepdf_theme`` as a reference for the expected
+directory structure and SCSS files.
+
+.. note:: If the theme module cannot be imported or does not define ``get_scss_sources_path()``,
+   the builder falls back to the bundled ``simplepdf_theme`` SCSS sources and emits a warning.w
 
 .. _theme_options:
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "flit_core.buildapi"
 
 [project]
 name = "sphinx-simplepdf"
-version = "1.7.0"
+version = "1.8.0"
 description = "An easy to use PDF Builder for Sphinx with a modern PDF-Theme."
 readme = "README.rst"
 license = "MIT"

sphinx_simplepdf/builders/simplepdf.py

@@ -101,28 +101,30 @@ def get_theme_option_var(self, name, default):
     def _resolve_scss_folder(self):
         """Resolve the SCSS sources folder from the configured theme package.
 
-        Tries to import the theme module specified by simplepdf_theme and use
-        its get_scss_sources_path() if available. Falls back to the bundled
-        simplepdf_theme if the external theme cannot be found.
+        Imports the theme module and calls its get_scss_sources_path(). Falls
+        back to the bundled simplepdf_theme if the theme cannot be imported or
+        does not define get_scss_sources_path().
         """
         theme_name = self.app.config.simplepdf_theme or "simplepdf_theme"
         try:
             theme_module = importlib.import_module(theme_name)
             if hasattr(theme_module, "get_scss_sources_path"):
                 return theme_module.get_scss_sources_path()
-            return os.path.join(
-                os.path.dirname(theme_module.__file__),
-                "static", "styles", "sources",
+            logger.warning(
+                f"Theme '{theme_name}' does not define get_scss_sources_path(), "
+                "falling back to bundled simplepdf_theme",
+                type="simplepdf",
+                subtype="theme",
             )
         except ImportError:
-            logger.info(
+            logger.warning(
                 f"Could not import theme '{theme_name}', "
-                "falling back to bundled simplepdf_theme"
-            )
-            return os.path.join(
-                os.path.dirname(__file__), "..", "themes",
-                "simplepdf_theme", "static", "styles", "sources",
+                "falling back to bundled simplepdf_theme",
+                type="simplepdf",
+                subtype="theme",
             )
+        from sphinx_simplepdf.themes.simplepdf_theme import get_scss_sources_path
+        return get_scss_sources_path()
 
     def finish(self) -> None:
         super().finish()

sphinx_simplepdf/themes/simplepdf_theme/__init__.py

@@ -14,6 +14,11 @@ def get_html_theme_path():
     return cur_dir
 
 
+def get_scss_sources_path():
+    """Return the absolute path to the SCSS sources directory."""
+    return path.join(path.abspath(path.dirname(__file__)), "static", "styles", "sources")
+
+
 # See http://www.sphinx-doc.org/en/stable/theming.html#distribute-your-theme-as-a-python-package
 def setup(app):
     app.add_html_theme("simplepdf_theme", path.abspath(path.dirname(__file__)))