Change Sphinx docs theme to Furo

Use the Furo theme, which provides a minimalist and yet modern interface, including light/dark color support and the new table of contents entries for API docs (see sphinx-doc/sphinx#6316).

- Change theme to Furo
- Install `furo` in the `docs` group
- Fix missing language configuration
- Turn off sidebar customization to use Furo default sidebars instead
- Add API docs link to main sidebar

docs/conf.py

@@ -74,7 +74,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -93,7 +93,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'nature'
+html_theme = "furo"
 
 # 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
@@ -111,16 +111,19 @@
 #
 # This is required for the alabaster theme
 # refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
-html_sidebars = {
-    '**': [
-        #'about.html',
-        #'navigation.html',
-        'globaltoc.html',  # show all pages' headers
-        'relations.html',  # needs 'show_related': True theme option to display
-        'searchbox.html',
-        #'donate.html',
-    ]
-}
+# html_sidebars = {
+#     '**': [
+#         #'about.html',
+#         #'navigation.html',
+#         'globaltoc.html',  # show all pages' headers
+#         'relations.html',  # needs 'show_related': True theme option to display
+#         'searchbox.html',
+#         #'donate.html',
+#     ]
+# }
+
+# Change table of contents formatting
+# toc_object_entries_show_parents = "domain"
 
 
 # -- Options for HTMLHelp output ------------------------------------------

docs/index.rst

@@ -16,6 +16,7 @@ Welcome to MagellanMapper's documentation!
    settings.md
    pipelines.md
    cloud_aws.md
+   API documentation <genindex>
 
 
 

setup.py

@@ -21,7 +21,12 @@
 _EXTRAS_AWS = ["boto3", "awscli"]
 
 # optional dependencies to build API documentation
-_EXTRAS_DOCS = ["sphinx", "sphinx-autodoc-typehints", "myst-parser"]
+_EXTRAS_DOCS = [
+    "sphinx",
+    "sphinx-autodoc-typehints",
+    "myst-parser",
+    "furo",  # theme
+]
 
 # optional dependencies for Jupyter notebooks
 _EXTRAS_JUPYTER = ["jupyterlab", "bash_kernel"]