Add banner and favicon to workflow documentation site

.github/workflows/fetch-and-compile-workflow-documentation.yml

@@ -29,9 +29,11 @@ jobs:
         run: |
           chmod +x ./src/ingesters/workflow_docs/fetch_docs_sources.sh
           ./src/ingesters/workflow_docs/fetch_docs_sources.sh
-      - name: Introduce additional source documents and a configuration file
+      - name: Introduce additional source files, static files, and a configuration file
         run: |
           cp -r src/ingesters/workflow_docs/metagenome_workflow_overview/docs /tmp/book/src/chapters/1_Metagenome_Workflow_Overview
+          cp    src/ingesters/workflow_docs/_static/js/index.js               /tmp/book/src/_static/js/index.js
+          cp    src/ingesters/workflow_docs/_static/favicon.ico               /tmp/book/src/_static/favicon.ico          
           cp    src/ingesters/workflow_docs/overview.rst                      /tmp/book/src/chapters/overview.rst
           cp    src/ingesters/workflow_docs/index.rst                         /tmp/book/src/index.rst
           cp    src/ingesters/workflow_docs/conf.py                           /tmp/book/src/conf.py

src/ingesters/workflow_docs/Dockerfile

@@ -32,6 +32,8 @@ RUN /tmp/fetch_docs_sources.sh
 # Introduce additional source documents and a configuration file.
 # Note: The above shell script will have created `/tmp/book/src/chapters/`.
 COPY metagenome_workflow_overview/docs /tmp/book/src/chapters/1_Metagenome_Workflow_Overview
+COPY _static/js/index.js               /tmp/book/src/_static/js/index.js
+COPY _static/favicon.ico               /tmp/book/src/_static/favicon.ico
 COPY overview.rst                      /tmp/book/src/chapters/overview.rst
 COPY index.rst                         /tmp/book/src/index.rst
 COPY conf.py                           /tmp/book/src/conf.py

src/ingesters/workflow_docs/_static/js/index.js

@@ -0,0 +1,39 @@
+(function () {
+    /**
+     * Create a banner and mount it to the DOM as the first element inside the `body`.
+     *
+     * @param innerHTML {string} The HTML content you want the banner to contain.
+     */
+    function displayBanner(innerHTML = "") {
+        const sphinxRTDSidebarEl = document.querySelector('.wy-side-nav-search');
+        const zIndexOfSphinxRTDSidebar = sphinxRTDSidebarEl !== null ? parseInt(window.getComputedStyle(sphinxRTDSidebarEl).zIndex) : 0;
+
+        const divEl = document.createElement("div");
+        divEl.style.backgroundColor = "red";
+        divEl.style.textAlign = "center";
+        divEl.style.zIndex = `${zIndexOfSphinxRTDSidebar + 1}`;
+        divEl.style.position = "relative";
+        divEl.style.paddingBottom = "2px";
+        divEl.innerHTML = innerHTML;
+        document.body.insertBefore(divEl, document.body.firstChild);
+
+        // Now that we've mounted the banner to the DOM, get its height in pixels and give the sidebar's search area
+        // that same number of pixels of top margin; that way, the banner won't cover that element. Also, do the same
+        // thing whenever the browser's width changes, since the banner's height could change in that situation, too.
+        sphinxRTDSidebarEl.style.marginTop = window.getComputedStyle(divEl).height;
+        addEventListener("resize", () => {
+            sphinxRTDSidebarEl.style.marginTop = window.getComputedStyle(divEl).height;
+        });
+    }
+
+    // Register a callback function to run when the web page has fully loaded.
+    window.addEventListener("load", (event) => {
+        displayBanner('<strong>This website is in early development.</strong> You can access our production documentation <a href="https://microbiomedata.org/documentation/" style="color: black;">here</a>.');
+    });
+
+    displayBanner(`
+        <strong>This website is in early development.</strong>
+        You can access our production documentation
+        <a href="https://microbiomedata.org/documentation/" style="color: black; text-decoration: underline;">here</a>.
+    `);
+})();

src/ingesters/workflow_docs/conf.py

@@ -26,3 +26,19 @@
 # The theme for HTML output.
 # Docs: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-master_doc
 html_theme = 'sphinx_rtd_theme'
+
+# Register paths to directories containing static files.
+# Note: This path is relative to the directory containing the `conf.py` file.
+# Reference: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_static_path
+html_static_path = ['_static']
+
+# Register a custom favicon for the website.
+# Reference: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_favicon
+html_favicon = '_static/favicon.ico'
+
+# Register a custom JavaScript script for the website to load.
+# Note: These paths are relative to the `{html_static_path}` directory.
+# Reference: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_js_files
+html_js_files = [
+    'js/index.js'
+]