Implement #419 review recommendations

docs/Makefile

@@ -6,6 +6,7 @@ SPHINXOPTS	=
 SPHINXBUILD   = sphinx-build
 PAPER		 =
 BUILDDIR	  = ../build/sphinx
+AUTOSUMMARYDIR    = source/_autosummary
 
 # User-friendly check for sphinx-build
 ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
@@ -47,6 +48,7 @@ help:
 	@echo "  doctest	to run all doctests embedded in the documentation (if enabled)"
 
 clean:
+	rm $(AUTOSUMMARYDIR)/*
 	rm -rf $(BUILDDIR)/*
 
 html:

docs/docs_requirements.txt

@@ -1,9 +1,9 @@
 -r ../requirements.txt
-sphinx>=4.2.0,<=5.3.0
+sphinx>=5.0.0
 sphinxcontrib-napoleon
 sphinxcontrib-bibtex
 sphinx-autodoc-typehints
-faculty-sphinx-theme
+furo
 jinja2<3.1.0  # temporary fix for jinja2/nbconvert bug
 traitlets!=5.2.2  # temporary fix for ipython/traitlets#741
 nbsphinx
@@ -12,4 +12,4 @@ ipython_genutils
 py2jn
 pygraphviz>=1.7
 pandoc
-docutils==0.16
+docutils>=0.18

docs/source/_static/scico.css

@@ -1,47 +1,23 @@
-/* Left hand navigation bar colours */
+/* furo theme customization */
 
-nav.wy-nav-side, nav.wy-nav-top {
-  background: #323232;
+.sidebar-drawer {
+  width: fit-content !important;
 }
 
-div.wy-side-nav-search a.heading:hover {
-  background-color: #575757;
+.main > .content {
+  min-width: 75%;
+  width: fit-content !important;
+  max-width: 80em;
 }
 
-
-/* Allow larger maximum width of main content */
-
-.wy-nav-content {
-  max-width: 1200px !important;
-}
-
-
-/* Footer */
-
-footer  {
-  font-size: 70%;
-}
-
-footer > div.rst-footer-buttons {
-  font-size: 125%;
+.highlight {
+  background: #f0ffe8;
 }
 
-
-/* Fix indices and tables spacing */
-
-#indices-and-tables p {
-  margin-bottom: 0;
-}
-
-
-/* Literal sections */
-
-div.highlight-default {
-  border: 0 !important;
-}
-
-div.highlight {
-  background-color: inherit;
+.sidebar-brand-text {
+  font-size: 1.0rem !important;
+  text-align: center;
+  padding-top: 0.5em;
 }
 
 
@@ -52,163 +28,78 @@ div.doctest.highlight-default {
 }
 
 
-/* Improve references layout */
-
-div.citation {
-  display: flex;
-}
-
-div.citation > span.label {
-  float: left;
-  padding-right: 0.8em;
-  padding-top: 0.1em;
-}
-
-
-/* Todo note */
-
-div.admonition-todo {
-  background-color: #f0c0b0 !important;
-}
-
-div.admonition-todo > p.admonition-title {
-  background-color: #ff2020 !important;
-}
-
-
-/* References layout and appearance */
-
-dl.citation {
-  display: grid;
-  grid-template-columns: max-content auto;
-}
-
-dl.citation > dt {
-  background-color: #ffffff !important;
-  border-top: 0 !important;
-  margin: 0 !important;
-  grid-column-start: 1;
-  width: 2em;
-}
-
-dl.citation > dd {
-  padding-bottom: 0 !important;
-  margin-bottom: 0 !important;
-  margin-left: 5px !important;
-  grid-column-start: 2;
-}
-
-
-/* Fix equation number location */
-
-.math {
-  text-align: left;
-}
-
-.eqno {
-  float: right;
-}
-
-
 /* Style for autosummary API docs */
 
-dl.field-list.simple {
+[data-theme=light] dl.field-list.simple {
   background-color: #f5f5f5;
   border-radius: 4px;
 }
 
-dl.field-list.simple > dt.field-odd {
+[data-theme=light] dl.field-list.simple > dt.field-odd {
   background-color: #f2f2f2;
-  border-bottom: solid 3px #c0c0c0;
   border-radius: 4px;
 }
 
-dl.field-list.simple > dt.field-even {
+[data-theme=light] dl.field-list.simple > dt.field-even {
   background-color: #f2f2f2;
-  border-bottom: solid 3px #c0c0c0;
   border-radius: 4px;
 }
 
-dl.py.data {
+[data-theme=light] dl.py.data {
   background-color: #fdfafa;
   border-radius: 4px;
 }
 
-dl.py.data > dt {
+[data-theme=light] dl.py.data > dt {
   border-radius: 4px;
 }
 
-dl.py.attribute {
+[data-theme=light] dl.py.attribute {
   background-color: #fdfafa;
   border-radius: 4px;
 }
 
-dl.py.attribute > dt {
+[data-theme=light] dl.py.attribute > dt {
   border-radius: 4px;
 }
 
-dl.py.function {
+[data-theme=light] dl.py.function {
   background-color: #fdfafa;
   border-radius: 4px;
 }
 
-dl.py.function > dt {
+[data-theme=light] dl.py.function > dt {
   border-radius: 4px;
 }
 
-dl.py.class {
+[data-theme=light] dl.py.function blockquote {
+  background-color: #f5f5f5;
+  border-left: 0px;
+}
+
+[data-theme=light] dl.py.class {
   background-color: #fdfafa;
   border-radius: 4px;
 }
 
-dl.py.class > dt {
+[data-theme=light] dl.py.class > dt {
   border-radius: 4px;
 }
 
-dl.py.method {
+[data-theme=light] dl.py.method {
   background-color: #f6f6f6;
   border-radius: 4px;
 }
 
-dl.py.method > dt {
-  border-top: solid 3px #c0c0c0 !important;
+[data-theme=light] dl.py.method > dt {
   border-radius: 4px;
 }
 
-dl.py.property {
+[data-theme=light] dl.py.property {
   background-color: #f6f6f6;
   border-radius: 4px;
 }
 
-dl.py.property > dt {
-  border-top: solid 3px #c0c0c0 !important;
+[data-theme=light] dl.py.property > dt {
   border-radius: 4px;
 }
-
-
-/* Temporary hack to improve autodoc class attribute layout */
-
-.py.class dl:not(.py.attribute) + .py.attribute::before {
-    content: "Attributes";
-    font-weight: bold;
-    font-size: 90%;
-    display: inline-block;
-    color: #555;
-    background-color: #f5f5f5;
-    padding: 4px;
-    margin-left: -3em;
-    margin-bottom: 15px;
-    border-radius: 4px;
-    border-bottom: solid 3px #c0c0c0;
-    border-left: solid 3px #c0c0c0;
-}
-
-.py.class dl.py.attribute {
-    padding-left: 3em;
-}
-
-.py.class dl.py.attribute > dt {
-    border-bottom: solid 3px #c0c0c0 !important;
-    border-left: solid 3px #c0c0c0 !important;
-    border-radius: 4px;
-}

docs/source/_templates/breadcrumbs.html

@@ -0,0 +1,4 @@
+{%- extends "sphinx_rtd_theme/breadcrumbs.html" %}
+
+{% block breadcrumbs_aside %}
+{% endblock %}

docs/source/_templates/sidebar/brand.html

@@ -0,0 +1,31 @@
+{#-
+
+Hi there!
+
+You might be interested in https://pradyunsg.me/furo/customisation/sidebar/
+
+Although if you're reading this, chances are that you're either familiar
+enough with Sphinx that you know what you're doing, or landed here from that
+documentation page.
+
+Hope your day's going well. :)
+
+-#}
+<a class="sidebar-brand{% if logo %} centered{% endif %}" href="{{ pathto(master_doc) }}">
+  {% block brand_content %}
+  {%- if logo_url %}
+  <div class="sidebar-logo-container">
+    <img class="sidebar-logo" src="{{ logo_url }}" alt="Logo"/>
+  </div>
+  {%- endif %}
+  {%- if theme_light_logo and theme_dark_logo %}
+  <div class="sidebar-logo-container">
+    <img class="sidebar-logo only-light" src="{{ pathto('_static/' + theme_light_logo, 1) }}" alt="Light Logo"/>
+    <img class="sidebar-logo only-dark" src="{{ pathto('_static/' + theme_dark_logo, 1) }}" alt="Dark Logo"/>
+  </div>
+  {%- endif %}
+  {% if not theme_sidebar_hide_name %}
+  <span class="sidebar-brand-text">{{ version }}</span>
+  {%- endif %}
+  {% endblock brand_content %}
+</a>

docs/source/advantages.rst

@@ -1,30 +1,6 @@
 Why SCICO?
 ==========
 
-
-.. raw:: html
-
-    <style type='text/css'>
-    div.document ul blockquote {
-       margin-bottom: 8px !important;
-    }
-    div.document li > p {
-       margin-bottom: 4px !important;
-    }
-    div.document ul > li {
-      list-style: square outside !important;
-      margin-left: 1em !important;
-    }
-    section {
-      padding-bottom: 1em;
-    }
-    ul {
-      margin-bottom: 1em;
-    }
-    </style>
-
-
-
 Advantages of JAX-based Design
 ------------------------------
 

docs/source/api.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 API Documentation
 =================