fix ReadTheDocs configuration (#227)

* update ReadTheDocs config to use new build block

* use a theme for the docs build

.readthedocs.yml

@@ -7,9 +7,17 @@ sphinx:
   configuration: docs/source/conf.py
   fail_on_warning: true
 
-# Set the version of Python and requirements required to build your docs
+build:
+  os: ubuntu-22.04
+  tools:
+    python: mambaforge-4.10
+
+conda:
+  environment: docs/rtd_environment.yaml
+
+# Set the Python requirements required to build your docs
 python:
-  version: 3.8
+  system_packages: false
   install:
     - method: pip
       path: .

docs/rtd_environment.yaml

@@ -0,0 +1,10 @@
+name: rtd311
+channels:
+ - conda-forge
+ - defaults
+dependencies:
+ - python=3.11
+ - pip
+ - graphviz
+ - pip:
+    - stsci_rtd_theme

docs/source/conf.py

@@ -14,6 +14,14 @@
 import os
 import sys
 
+import stsci_rtd_theme
+
+def setup(app):
+    try:
+        app.add_css_file("stsci.css")
+    except AttributeError:
+        app.add_stylesheet("stsci.css")
+
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
@@ -100,15 +108,22 @@
 
 # The theme to use for HTML and HTML Help pages.  Major themes that come with
 # Sphinx are currently 'default' and 'sphinxdoc'.
-# html_theme = 'default'
+html_theme = 'stsci_rtd_theme'
 
 # 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 = {}
+html_theme_options = {
+    "collapse_navigation": True
+    # "nosidebar": "false",
+    # "sidebarbgcolor": "#4db8ff",
+    # "sidebartextcolor": "black",
+    # "sidebarlinkcolor": "black",
+    # "headbgcolor": "white",
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
-#html_theme_path = []
+html_theme_path = [stsci_rtd_theme.get_html_theme_path()]
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
@@ -204,4 +219,6 @@
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'http://docs.python.org/': None}
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3/', None),
+}

pyproject.toml

@@ -34,6 +34,7 @@ calcos = "calcos:main"
 [project.optional-dependencies]
 docs = [
     "sphinx",
+    "stsci_rtd_theme",
 ]
 test = [
     "ci-watson",