MAINT: split bootstrap and theme styling (#994)

Author: 12rambau

pyproject.toml

@@ -8,6 +8,8 @@ theme-name = "pydata_sphinx_theme"
 additional-compiled-static-assets = [
   "webpack-macros.html",
   "vendor/",
+  "styles/bootstrap.css",
+  "scripts/bootstrap.js"
 ]
 
 [project]

src/pydata_sphinx_theme/assets/scripts/bootstrap.js

@@ -0,0 +1,18 @@
+/* Import and setup functions to control Bootstrap's behavior.
+ * Sphinx injects the html output with jquery and other javascript files. To enable
+ * Popper.js (and other jQuery plugins) to hook into the same instance of jQuery,
+ * jQuery is defined as a Webpack external, thus this import uses the externally defined jquery dependency.
+ */
+import "jquery";
+import "popper.js";
+import "bootstrap";
+
+import "../styles/bootstrap.scss";
+
+/*******************************************************************************
+ * Call functions after document loading.
+ * This is equivalent to the .ready() function as described in
+ * https://api.jquery.com/ready/
+ */
+
+$('[data-toggle="tooltip"]').tooltip({ delay: { show: 500, hide: 100 } });

src/pydata_sphinx_theme/assets/scripts/index.js renamed to src/pydata_sphinx_theme/assets/scripts/pydata-sphinx-theme.js

@@ -1,13 +1,10 @@
 /* Sphinx injects the html output with jquery and other javascript files.
- * To enable Popper.js (and other jQuery plugins) to hook into the same instance of jQuery,
- * jQuery is defined as a Webpack external, thus this import uses the externally defined jquery dependency.
+ * for jQuery plugin, jQuery is defined as a Webpack external, thus this import
+ * uses the externally defined jquery dependency.
  */
 import "jquery";
 
-import "popper.js";
-import "bootstrap";
-
-import "../styles/index.scss";
+import "../styles/pydata-sphinx-theme.scss";
 
 /*******************************************************************************
  * Theme interaction
@@ -378,14 +375,13 @@ function initRTDObserver() {
 }
 
 /*******************************************************************************
- * Finalize
+ * Call functions after document loading.
+ * This is equivalent to the .ready() function as described in
+ * https://api.jquery.com/ready/
  */
 
-// This is equivalent to the .ready() function as described in
-// https://api.jquery.com/ready/
 $(addModeListener);
 $(scrollToActive);
 $(addTOCInteractivity);
 $(setupSearchButtons);
-$('[data-toggle="tooltip"]').tooltip({ delay: { show: 500, hide: 100 } });
 $(initRTDObserver);

src/pydata_sphinx_theme/assets/styles/bootstrap.scss

@@ -0,0 +1,5 @@
+// create a specific css file to build bootstrap css
+// the objective is to split css coming from bootstrap from the one coming from
+// the theme itself
+@import "variables/bootstrap";
+@import "~bootstrap/scss/bootstrap";

src/pydata_sphinx_theme/assets/styles/index.scss renamed to src/pydata_sphinx_theme/assets/styles/pydata-sphinx-theme.scss

@@ -1,22 +1,8 @@
 // Import Bootstrap core
-// Override bootstrap variables
-$spacer: 1rem;
-
-$container-max-widths: (
-  sm: 540px,
-  md: 720px,
-  lg: 960px,
-  xl: 1400px,
-);
-
-$grid-breakpoints: (
-  xs: 0,
-  sm: 540px,
-  md: 720px,
-  lg: 960px,
-  xl: 1200px,
-);
-@import "~bootstrap/scss/bootstrap";
+@import "~bootstrap/scss/functions";
+@import "variables/bootstrap";
+@import "~bootstrap/scss/variables";
+@import "~bootstrap/scss/mixins";
 
 // Variables
 @import "variables/layout";

src/pydata_sphinx_theme/assets/styles/variables/_bootstrap.scss

@@ -0,0 +1,17 @@
+// Override bootstrap variables
+$spacer: 1rem;
+
+$container-max-widths: (
+  sm: 540px,
+  md: 720px,
+  lg: 960px,
+  xl: 1400px,
+);
+
+$grid-breakpoints: (
+  xs: 0,
+  sm: 540px,
+  md: 720px,
+  lg: 960px,
+  xl: 1200px,
+);

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/static/.gitignore

@@ -1,6 +1,15 @@
+# theme generated webpack outputs
 scripts/pydata-sphinx-theme.js
 scripts/pydata-sphinx-theme.js.map
 styles/pydata-sphinx-theme.css
 styles/pydata-sphinx-theme.css.map
+
+# bootstrap generated webpack outputs
+scripts/bootstrap.js
+scripts/bootstrap.js.map
+styles/bootstrap.css
+styles/bootstrap.css.map
+
+# webpack files
 webpack-macros.html
 vendor/*

webpack.config.js

@@ -20,6 +20,8 @@ const dedent = require("dedent");
 //
 // Paths for various assets (sources and destinations)
 //
+
+const scriptPath = resolve(__dirname, "src/pydata_sphinx_theme/assets/scripts");
 const staticPath = resolve(
   __dirname,
   "src/pydata_sphinx_theme/theme/pydata_sphinx_theme/static"
@@ -36,10 +38,24 @@ const vendorPaths = {
 // Cache-busting Jinja2 macros (`webpack-macros.html`) used in `layout.html`
 //
 function macroTemplate({ compilation }) {
+  // add a hash keep for each build
   const hash = compilation.hash;
+
   // We load these files into the theme via HTML templates
-  const css_files = ["styles/theme.css", "styles/pydata-sphinx-theme.css"];
-  const js_files = ["scripts/pydata-sphinx-theme.js"];
+  const css_files = [
+    "styles/theme.css", // basic sphinx css
+    "styles/bootstrap.css", // all bootstrap 5 css with variable adjustments
+    "styles/pydata-sphinx-theme.css", // all the css created for this specific theme
+  ];
+  const js_files = ["scripts/bootstrap.js", "scripts/pydata-sphinx-theme.js"];
+  const icon_files = [
+    `vendor/fontawesome/${vendorVersions.fontAwesome}/webfonts/fa-solid-900.woff2`,
+    `vendor/fontawesome/${vendorVersions.fontAwesome}/webfonts/fa-brands-400.woff2`,
+    `vendor/fontawesome/${vendorVersions.fontAwesome}/webfonts/fa-regular-400.woff2`,
+  ];
+  const font_files = [
+    `vendor/fontawesome/${vendorVersions.fontAwesome}/css/all.min.css`,
+  ];
 
   // Load a CSS script with a digest for cache busting.
   function stylesheet(css) {
@@ -56,29 +72,20 @@ function macroTemplate({ compilation }) {
     return `<script src="{{ pathto('_static/${js}', 1) }}?digest=${hash}"></script>`;
   }
 
+  // Load the fonts as preload files
+  function font(woff2) {
+    return `<link rel="preload" as="font" type="font/woff2" crossorigin href="{{ pathto('_static/${woff2}', 1) }}">`;
+  }
+
   return dedent(`\
     <!--
       AUTO-GENERATED from webpack.config.js, do **NOT** edit by hand.
       These are re-used in layout.html
     -->
     {# Load FontAwesome icons #}
     {% macro head_pre_icons() %}
-      <link rel="stylesheet"
-        href="{{ pathto('_static/vendor/fontawesome/${
-          vendorVersions.fontAwesome
-        }/css/all.min.css', 1) }}">
-      <link rel="preload" as="font" type="font/woff2" crossorigin
-        href="{{ pathto('_static/vendor/fontawesome/${
-          vendorVersions.fontAwesome
-        }/webfonts/fa-solid-900.woff2', 1) }}">
-      <link rel="preload" as="font" type="font/woff2" crossorigin
-        href="{{ pathto('_static/vendor/fontawesome/${
-          vendorVersions.fontAwesome
-        }/webfonts/fa-brands-400.woff2', 1) }}">
-      <link rel="preload" as="font" type="font/woff2" crossorigin
-        href="{{ pathto('_static/vendor/fontawesome/${
-          vendorVersions.fontAwesome
-        }/webfonts/fa-regular-400.woff2', 1) }}">
+      ${font_files.map(stylesheet).join("\n")}
+      ${icon_files.map(font).join("\n")}
     {% endmacro %}
 
     {% macro head_pre_assets() %}
@@ -102,9 +109,8 @@ module.exports = {
   mode: "production",
   devtool: "source-map",
   entry: {
-    "pydata-sphinx-theme": [
-      "./src/pydata_sphinx_theme/assets/scripts/index.js",
-    ],
+    "pydata-sphinx-theme": resolve(scriptPath, "pydata-sphinx-theme.js"),
+    bootstrap: resolve(scriptPath, "bootstrap.js"),
   },
   output: {
     filename: "scripts/[name].js",
@@ -126,7 +132,7 @@ module.exports = {
           {
             loader: "file-loader",
             options: {
-              name: "styles/pydata-sphinx-theme.css",
+              name: "styles/[name].css",
             },
           },
           {