Switch to furo theme (#297)

Author: shnizzedy

CONTRIBUTING.md

@@ -112,12 +112,15 @@ Steps to build this documentation locally:
 ```
 
 where `{width}` and `{height}` are the values already present in the existing `width` and `height` XML attributes.
-- Load SVGs in HTML `object` elements with the `raw:: html` directive to preserve hyperlinks and scaling:
+- Embed SVGs with the `raw:: html` directive to preserve hyperlinks. Since the `svg-flowchart` container scales SVGs to the page width, add a link below to view them at their original scale:
 
 ```rst
-.. raw:: html
+.. container:: svg-flowchart
 
-    <object data="../_static/path/to/chart.svg" type="image/svg+xml"></object>
+    .. raw:: html
+        :file: ../_static/path/to/chart.svg
+
+    `Open image <../_static/path/to/chart.svg>`_
 ```
 
 <a id="markdown-tutorials" name="tutorials"></a>

docs/_sources/_static/custom.css

@@ -1,61 +1,20 @@
-:root {
-  --bg-dark: #11303D;
-  --bg-light: #F0F0F0;
+/* docs version dropdown: top bar */
+.brand > select {
+  background: transparent;
+  border: none;
+  color: var(--color-header-text);
 }
 
-html {
-  background-color: var(--bg-dark, #11303D);
+/* docs version dropdown: side bar */
+.sidebar-brand-text > select {
+    background-color: transparent;
+    border: none;
+    color: var(--color-sidebar-link-text--top-level);
+    text-decoration: underline;
+    text-decoration-color: var(--color-link-underline);
 }
 
-body {
-  background-color: var(--bg-light, #F0F0F0);
-}
-
-div.body {
-  max-width: 100%;
-}
-div.bodywrapper p {
-  margin-block: 0;
-}
-div.bodywrapper section {
-  background-color: white;
-  padding: 0 20px 30px 20px;
-}
-div.bodywrapper section > p {
-  padding-bottom: 1ex;
-}
-div.bodywrapper section h2 {
-  margin-block-start: 0;
-  padding-block-start: 0.83em;
-}
-div.citation p {
-  display: inline;
-}
-div.flowchart-container {
-  max-width: 1200px;
-}
-div.footer {
-  background-color: var(--bg-dark, #11303D);
-}
-div.sphinxsidebar {
-  background-color: var(--bg-light, #F0F0F0);
-}
-
-object {
-  max-width: 100%;
-}
-
-.bibtex .brackets::before {
-  content: "[";
-}
-.bibtex .brackets::after {
-  content: "]"
-}
-
-.bibtex.label {
-  display: grid;
-}
-
-section[id^="Tutorial:"] p img {
-  max-width: 80%;
+.svg-flowchart > svg {
+  width: 100%;
+  height: auto;
 }

scripts/versionList.js renamed to docs/_sources/_static/versionList.js

@@ -24,9 +24,10 @@ function createDropdown(here) {
 function versionDropdown() {
   const here = window.location.href;
   const dochome = "https://" + here.split('/').slice(2, 5).join('/');
-  const navTitles = document.getElementsByClassName("nav-item-0");
+  const navTitles = document.querySelectorAll(".brand,.sidebar-brand-text");
   createDropdown(here).then(dropdown => {
     for (let item of navTitles) {
+      item.parentElement.removeAttribute("href");
       let newTitle = document.createElement("div");
       let newTitlePrefix = document.createElement("a");
       newTitlePrefix.setAttribute("href", dochome);

docs/_sources/_templates/layout.html

@@ -9,5 +9,4 @@
       gtag('js', new Date());
       gtag('config', 'UA-19224662-10');
     </script>
-    <script defer src="https://fcp-indi.github.io/scripts/versionList.js"></script>
 {% endblock %}

docs/_sources/conf.py

@@ -141,7 +141,6 @@ def yaml_to_rst(path):
 extensions = [
     'sphinx.ext.autodoc',
     'sphinxcontrib.bibtex',
-    'sphinxcontrib.fulltoc',
     'sphinx.ext.ifconfig',
     'sphinx.ext.intersphinx',
     'sphinx.ext.mathjax',
@@ -172,7 +171,7 @@ def yaml_to_rst(path):
 
 # General information about the project.
 project = 'C-PAC'
-copyright = '2012‒2022, C-PAC Developers. C-PAC is licensed under LGPL-3' \
+copyright = '2012‒2023, C-PAC Developers. C-PAC is licensed under LGPL-3' \
             '.0-or-later'
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -408,25 +407,7 @@ def _unireplace(release_note, unireplace):
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'classic'
-
-# Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
-# documentation.
-html_theme_options = {
-    'relbarbgcolor': '#0067a0',
-    'sidebarbgcolor': '#f0f0f0',
-    'sidebartextcolor': '#000000',
-    'sidebarlinkcolor': '#0067a0',
-    'headbgcolor': '#919d9d',
-    'headtextcolor': '#e4e4e4'
-}
-
-# Add any paths that contain custom themes here, relative to this directory.
-html_theme_path = ['../Themes']
-html_css_files = [
-    'custom.css',
-]
+html_theme = 'furo'
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # '<project> v<release> documentation'.
@@ -449,6 +430,14 @@ def _unireplace(release_note, unireplace):
 # so a file named 'default.css' will overwrite the builtin 'default.css'.
 html_static_path = ['_static']
 
+# These paths are either relative to html_static_path
+# or fully qualified paths (eg. https://...)
+html_css_files = [
+    'custom.css',
+]
+html_js_files = [
+    ('versionList.js', {'defer': 'defer'})]
+
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
 # html_last_updated_fmt = '%b %d, %Y'
@@ -457,15 +446,6 @@ def _unireplace(release_note, unireplace):
 # typographically correct entities.
 # html_use_smartypants = True
 
-# Custom sidebar templates, maps document names to template names.
-html_sidebars = {
-  '**': [
-    'localtoc.html',
-    # 'globaltoc.html',
-    'searchbox.html'
-  ]
- }
-
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
 # html_additional_pages = {}

docs/_sources/developer/continuous_integration.rst

@@ -3,6 +3,9 @@ Continuous Integration
 
 Our continous integration flow relies on GitHub Actions, GitHub Container Registry, CircleCI and Docker Hub. GitHub Actions builds staging images based on changes to Dockerfiles and pushes those images to GitHub Container Registry. On each push, once staging images are built or determined to be up to date, GitHub Actions installs C-PAC into a development image for each variant (standard, lite, fMRIPrep-LTS, and ABCD-HCP). CircleCI runs tests in both Docker and Singularity for each of these images and generates a coverage report if all tests pass. On release, CircleCI also pushes production images to Docker Hub.
 
-.. raw:: html
+.. container:: svg-flowchart
 
-    <div class="flowchart-container"><object data="../_static/flowcharts/CI-flow.svg" type="image/svg+xml"></object></div>
+    .. raw:: html
+        :file: ../_static/flowcharts/CI-flow.svg
+
+    `Open image <../_static/flowcharts/CI-flow.svg>`_

docs/_sources/developer/logging.rst

@@ -3,9 +3,12 @@ Logging
 
 Most C-PAC logging is handled by the built-in Python ``logging`` library. When logging, take care to choose an appropriate ``getLogger`` function or method. While :py:func:`CPAC.utils.monitoring.custom_logging.getLogger` and ``nipype.utils.logger.Logging.getLogger`` each fall back on ``logging.getLogger``,
 
-.. raw:: html
+.. container:: svg-flowchart
 
-    <div class="flowchart-container"><object data="../_static/flowcharts/getLogger.svg" type="image/svg+xml"></object></div>
+    .. raw:: html
+        :file: ../_static/flowcharts/getLogger.svg
+
+    `Open image <../_static/flowcharts/getLogger.svg>`_
 
 
 each have their own intended use cases.

docs/_sources/user/anat.rst

@@ -1,9 +1,12 @@
 Anatomical Preprocessing
 ------------------------
 
-.. raw:: html
+.. container:: svg-flowchart
 
-    <div class="flowchart-container"><object data="../_static/flowcharts/anatomical.svg" type="image/svg+xml"></object></div>
+    .. raw:: html
+        :file: ../_static/flowcharts/anatomical.svg
+
+    `Open image <../_static/flowcharts/anatomical.svg>`_
 
 Surface Analysis
 ^^^^^^^^^^^^^^^^
@@ -294,9 +297,12 @@ Configuring CPAC to Run Anatomical Registration
 Anatomical Tissue Segmentation
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. raw:: html
+.. container:: svg-flowchart
+
+    .. raw:: html
+        :file: ../_static/flowcharts/segmentation.svg
 
-    <div class="flowchart-container"><object data="../_static/flowcharts/segmentation.svg" type="image/svg+xml"></object></div>
+    `Open image <../_static/flowcharts/segmentation.svg>`_
 
 C-PAC uses `FSL/FAST <http://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FAST>`_ to automatically segment brain images into white matter, gray matter, and CSF. This is done using probability maps that contain information about the likelihood that a given voxel will be of a particular tissue type. Users specify a probability threshold such that voxels meeting a minimum probability of being a particular tissue will be classified as such. This results in masks containing voxels of only a single tissue type.
 

docs/_sources/user/compute_config.rst

@@ -13,9 +13,12 @@ Computer Settings
 
 #. **Observed Usage:** The resource usage of each node depends on many factors, including the data, the pipeline configuration, and the system. To run many subjects with optimimzed resource estimation, first run a single subject with the desired number of cores and with a generous memory limit. Then, provide the ``callback.log`` generated from that initial run when you run the rest of the subjects.
 
-    .. raw:: html
+    .. container:: svg-flowchart
 
-        <object data="../_static/flowcharts/observed-usage.svg" type="image/svg+xml"></object>
+        .. raw:: html
+            :file: ../_static/flowcharts/observed-usage.svg
+
+        `Open image <../_static/flowcharts/observed-usage.svg>`_
 
     #. **Callback log - [text]:** The path to a callback log file from a previous run, including any resource-management parameters that will be applied in this run, like ``n_cpus`` and ``num_ants_threads``. This file is used override memory estimates with previously observed memory usage. Can be overridden with the commandline flag ``--runtime_usage``.
     #. **Buffer - [percent]:** A percent of the previously observed memory usage that is to be added to the memory estimate. Default: 10. Can be overridden with the commandline flag ``--runtime_buffer``.

docs/_sources/user/func.rst

@@ -1,9 +1,12 @@
 Functional Preprocessing
 -------------------------
 
-.. raw:: html
+.. container:: svg-flowchart
 
-    <div class="flowchart-container"><object data="../_static/flowcharts/functional.svg" type="image/svg+xml"></object></div>
+    .. raw:: html
+        :file: ../_static/flowcharts/functional.svg
+
+    `Open image <../_static/flowcharts/functional.svg>`_
 
 Initial Preprocessing
 ^^^^^^^^^^^^^^^^^^^^^