Fix the ReadTheDocs setup (#1099)

* Fix Sphinx and sphinx-rtd-theme versions and update the code to make
  it work.
* Use sphinx-rtd-theme instead of alabaster. This makes the appearance
  consistent with GHC and Cabal RTD.

.readthedocs.yml

@@ -5,7 +5,11 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.7"
+    python: "3.10"
+
+python:
+  install:
+    - requirements: containers/docs/requirements.txt
 
 sphinx:
   configuration: containers/docs/conf.py

CONTRIBUTING.md

@@ -89,4 +89,4 @@ The "user's manual" is served by ReadTheDocs at
 https://haskell-containers.readthedocs.io and live in the `docs/` directory. To
 build it locally run `pip install sphinx sphinx-autobuild sphinx_rtd_theme` to
 install the dependencies, `git submodule update --init`, and then
-`cd docs/ && make html`.
+`cd containers/docs/ && make html`.

containers/docs/_extensions/hs-theme.py

@@ -1,2 +1,2 @@
 def setup(app):
-    app.add_stylesheet('css/hs-theme.css')
+    app.add_css_file('css/hs-theme.css')

containers/docs/conf.py

@@ -19,11 +19,12 @@
 extensions = ['sphinx.ext.intersphinx',
               'sphinx.ext.ifconfig',
               'haddock-autolink',
+              'sphinx_rtd_theme',
               'hs-theme']
 
 templates_path = ['_templates']
 
-source_suffix = '.rst'
+source_suffix = {'.rst': 'restructuredtext'}
 
 master_doc = 'index'
 
@@ -39,7 +40,7 @@
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
-language = None
+language = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -55,16 +56,10 @@
 
 # -- Options for HTML output ----------------------------------------------
 
-# on_rtd is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org
-on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
-
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-if not on_rtd:  # only import and set the theme if we're building docs locally
-    import sphinx_rtd_theme
-    html_theme = 'sphinx_rtd_theme'
-    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+html_theme = 'sphinx_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
@@ -84,18 +79,5 @@
     "github_user": "haskell",
     "github_repo": 'containers',
     "github_version": "master/",
-    "conf_py_path": "docs/",
-    "source_suffix": '.rst',
-}
-
-# Custom sidebar templates, must be a dictionary that maps document names
-# to template names.
-#
-# This is required for the alabaster theme
-# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
-html_sidebars = {
-    '**': [
-        'relations.html',  # needs 'show_related': True theme option to display
-        'searchbox.html',
-    ]
+    "conf_py_path": "containers/docs/",
 }

containers/docs/map.rst

@@ -77,7 +77,7 @@ The following GHCi session shows some of the basic map functionality::
     > fromList [(1,"one"),(2,"two"),(3,"new three"),(4,"newer four")]
 
 .. TIP:: You can use the `OverloadedLists
-	 <https://downloads.haskell.org/ghc/latest/docs/users_guide/exts/overloaded_lists.html>`_
+     <https://downloads.haskell.org/ghc/latest/docs/users_guide/exts/overloaded_lists.html>`_
      extension so you don't need to write ``fromList [1, 2, 3]`` everywhere;
      instead you can just write ``[1, 2, 3]`` and if the function is
      expecting a map it will be converted automatically! The code here

containers/docs/requirements.txt

@@ -0,0 +1,2 @@
+Sphinx==8.1.3
+sphinx-rtd-theme==3.0.2

containers/docs/set.rst

@@ -74,7 +74,7 @@ The following GHCi session shows some of the basic set functionality::
 
 
 .. TIP:: You can use the `OverloadedLists
-	 <https://downloads.haskell.org/ghc/latest/docs/users_guide/exts/overloaded_lists.html>`_
+     <https://downloads.haskell.org/ghc/latest/docs/users_guide/exts/overloaded_lists.html>`_
      extension so you don't need to write ``fromList [1, 2, 3]`` everywhere.
      Instead you can just write ``[1, 2, 3]`` and if the function is
      expecting a set it will be converted automatically! The code here