scikit-learn · Charlie-XIAO · Jan 31, 2024 · Feb 7, 2024 · Feb 8, 2024 · Feb 8, 2024
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -121,9 +121,11 @@ workflows:
       - doc:
           requires:
             - lint
-      - doc-min-dependencies:
-          requires:
-            - lint
+      # TODO: fix the minimum dependencies for documentation build when merging into
+      # the main branch and uncomment this block.
+      # - doc-min-dependencies:
+      #     requires:
+      #       - lint
       - deploy:
           requires:
             - doc
diff --git a/.gitignore b/.gitignore
@@ -15,9 +15,13 @@ dist/
 MANIFEST
 doc/sg_execution_times.rst
 doc/_build/
+doc/api/*.rst
 doc/auto_examples/
+doc/css/*
+!doc/css/.gitkeep
 doc/modules/generated/
 doc/datasets/generated/
+doc/index.rst
 doc/min_dependency_table.rst
 doc/min_dependency_substitutions.rst
 *.pdf

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -27,3 +27,10 @@ repos:
     # TODO: add the double-quote-cython-strings hook when it's usability has improved:
     # possibility to pass a directory and use it as a check instead of auto-formatter.
     -   id: cython-lint
+-   repo: https://github.com/pre-commit/mirrors-prettier
+    rev: v2.7.1
+    hooks:
+    -   id: prettier
+        files: ^doc/scss/|^doc/js/scripts/
+        exclude: ^doc/js/scripts/vendor/
+        types_or: ["scss", "javascript"]
diff --git a/build_tools/circle/build_doc.sh b/build_tools/circle/build_doc.sh
@@ -190,17 +190,13 @@ export OMP_NUM_THREADS=1
 if [[ "$CIRCLE_BRANCH" =~ ^main$ && -z "$CI_PULL_REQUEST" ]]
 then
     # List available documentation versions if on main
-    python build_tools/circle/list_versions.py > doc/versions.rst
+    python build_tools/circle/list_versions.py --json doc/versions.json --rst doc/versions.rst
 fi
 
 
 # The pipefail is requested to propagate exit code
 set -o pipefail && cd doc && make $make_args 2>&1 | tee ~/log.txt
 
-# Insert the version warning for deployment
-find _build/html/stable -name "*.html" | xargs sed -i '/<\/body>/ i \
-\    <script src="https://scikit-learn.org/versionwarning.js"></script>'
-
 cd -
 set +o pipefail
 
@@ -244,7 +240,7 @@ then
     (
     echo '<html><body><ul>'
     echo "$affected" | sed 's|.*|<li><a href="&">&</a> [<a href="https://scikit-learn.org/dev/&">dev</a>, <a href="https://scikit-learn.org/stable/&">stable</a>]</li>|'
-    echo '</ul><p>General: <a href="index.html">Home</a> | <a href="modules/classes.html">API Reference</a> | <a href="auto_examples/index.html">Examples</a></p>'
+    echo '</ul><p>General: <a href="index.html">Home</a> | <a href="api/index.html">API Reference</a> | <a href="auto_examples/index.html">Examples</a></p>'
     echo '<strong>Sphinx Warnings in affected files</strong><ul>'
     echo "$warnings" | sed 's/\/home\/circleci\/project\//<li>/g'
     echo '</ul></body></html>'

diff --git a/build_tools/circle/doc_environment.yml b/build_tools/circle/doc_environment.yml
@@ -33,7 +33,11 @@ dependencies:
   - polars
   - pooch
   - sphinxext-opengraph
+  - sphinx-remove-toctrees
+  - sphinx-design
+  - pydata-sphinx-theme
   - pip
   - pip:
     - jupyterlite-sphinx
     - jupyterlite-pyodide-kernel
+    - sphinxcontrib-sass
diff --git a/build_tools/circle/doc_linux-64_conda.lock b/build_tools/circle/doc_linux-64_conda.lock
diff --git a/build_tools/circle/doc_min_dependencies_environment.yml b/build_tools/circle/doc_min_dependencies_environment.yml
@@ -31,7 +31,11 @@ dependencies:
   - sphinx-prompt=1.3.0  # min
   - plotly=5.14.0  # min
   - polars=0.20.23  # min
-  - pooch
+  - pooch=1.6.0  # min
+  - sphinx-remove-toctrees=0.0.3  # min
+  - sphinx-design=0.5.0  # min
+  - pydata-sphinx-theme=0.15.2  # min
   - pip
   - pip:
     - sphinxext-opengraph==0.4.2  # min
+    - sphinxcontrib-sass==0.3.4  # min
diff --git a/build_tools/circle/doc_min_dependencies_linux-64_conda.lock b/build_tools/circle/doc_min_dependencies_linux-64_conda.lock
@@ -1,6 +1,6 @@
 # Generated by conda-lock.
 # platform: linux-64
-# input_hash: 08b61aae27c59a8d35d008fa2f947440f3cbcbc41622112e33e68f90d69b621c
+# input_hash: cafe7cd61ad4a74ea21c87f60f9b238a1a71ca72eb954e027ef20d13a6f3ca33
 @EXPLICIT
 https://conda.anaconda.org/conda-forge/linux-64/_libgcc_mutex-0.1-conda_forge.tar.bz2#d7c89558ba9fa0495403155b64376d81
 https://conda.anaconda.org/conda-forge/linux-64/ca-certificates-2024.2.2-hbcca054_0.conda#2f4327a1cbe7f022401b236e915a5fef
@@ -110,6 +110,7 @@ https://conda.anaconda.org/conda-forge/linux-64/xcb-util-renderutil-0.3.9-hd5903
 https://conda.anaconda.org/conda-forge/linux-64/xcb-util-wm-0.4.1-h8ee46fc_1.conda#90108a432fb5c6150ccfee3f03388656
 https://conda.anaconda.org/conda-forge/linux-64/xorg-libx11-1.8.9-h8ee46fc_0.conda#077b6e8ad6a3ddb741fce2496dd01bec
 https://conda.anaconda.org/conda-forge/noarch/alabaster-0.7.16-pyhd8ed1ab_0.conda#def531a3ac77b7fb8c21d17bb5d0badb
+https://conda.anaconda.org/conda-forge/noarch/appdirs-1.4.4-pyh9f0ad1d_0.tar.bz2#5f095bc6454094e96f146491fd03633b
 https://conda.anaconda.org/conda-forge/linux-64/brotli-python-1.1.0-py39h3d6467e_1.conda#c48418c8b35f1d59ae9ae1174812b40a
 https://conda.anaconda.org/conda-forge/linux-64/c-compiler-1.7.0-hd590300_1.conda#e9dffe1056994133616378309f932d77
 https://conda.anaconda.org/conda-forge/noarch/certifi-2024.2.2-pyhd8ed1ab_0.conda#0876280e409658fc6f9e75d035960333
@@ -124,7 +125,7 @@ https://conda.anaconda.org/conda-forge/linux-64/docutils-0.19-py39hf3d152e_1.tar
 https://conda.anaconda.org/conda-forge/noarch/exceptiongroup-1.2.0-pyhd8ed1ab_2.conda#8d652ea2ee8eaee02ed8dc820bc794aa
 https://conda.anaconda.org/conda-forge/noarch/execnet-2.1.1-pyhd8ed1ab_0.conda#15dda3cdbf330abfe9f555d22f66db46
 https://conda.anaconda.org/conda-forge/linux-64/fontconfig-2.14.2-h14ed4e7_0.conda#0f69b688f52ff6da70bccb7ff7001d1d
-https://conda.anaconda.org/conda-forge/noarch/fsspec-2024.3.1-pyhca7485f_0.conda#b7f0662ef2c9d4404f0af9eef5ed2fde
+https://conda.anaconda.org/conda-forge/noarch/fsspec-2024.5.0-pyhff2d567_0.conda#d73e9932511ef7670b2cc0ebd9dfbd30
 https://conda.anaconda.org/conda-forge/linux-64/gfortran-12.3.0-h915e2ae_7.conda#8efa768f7f74085629f3e1090e7f0569
 https://conda.anaconda.org/conda-forge/linux-64/gfortran_linux-64-12.3.0-h617cb40_3.conda#3a9e5b8a6f651ff14e74d896d8f04ab6
 https://conda.anaconda.org/conda-forge/linux-64/glib-tools-2.80.2-hb6ce0ca_0.conda#a965aeaf060289528a3fbe09326edae2
@@ -146,7 +147,6 @@ https://conda.anaconda.org/conda-forge/linux-64/markupsafe-2.1.5-py39hd1e30aa_0.
 https://conda.anaconda.org/conda-forge/noarch/networkx-3.2-pyhd8ed1ab_0.conda#cec8cc498664cc00a070676aa89e69a7
 https://conda.anaconda.org/conda-forge/linux-64/openjpeg-2.5.2-h488ebb8_0.conda#7f2e286780f072ed750df46dc2631138
 https://conda.anaconda.org/conda-forge/noarch/packaging-24.0-pyhd8ed1ab_0.conda#248f521b64ce055e7feae3105e7abeb8
-https://conda.anaconda.org/conda-forge/noarch/platformdirs-4.2.2-pyhd8ed1ab_0.conda#6f6cf28bf8e021933869bae3f84b8fc9
 https://conda.anaconda.org/conda-forge/noarch/pluggy-1.5.0-pyhd8ed1ab_0.conda#d3483c8fc2dc2cc3f5cf43e26d60cabf
 https://conda.anaconda.org/conda-forge/noarch/ply-3.11-pyhd8ed1ab_2.conda#18c6deb6f9602e32446398203c8f0e91
 https://conda.anaconda.org/conda-forge/linux-64/psutil-5.9.8-py39hd1e30aa_0.conda#ec86403fde8793ac1c36f8afa3d15902
@@ -158,6 +158,7 @@ https://conda.anaconda.org/conda-forge/linux-64/pyyaml-6.0.1-py39hd1e30aa_1.cond
 https://conda.anaconda.org/conda-forge/linux-64/setuptools-59.8.0-py39hf3d152e_1.tar.bz2#4252d0c211566a9f65149ba7f6e87aa4
 https://conda.anaconda.org/conda-forge/noarch/six-1.16.0-pyh6c4a22f_0.tar.bz2#e5f25f8dbc060e9a8d912e432202afc2
 https://conda.anaconda.org/conda-forge/noarch/snowballstemmer-2.2.0-pyhd8ed1ab_0.tar.bz2#4d22a9315e78c6827f806065957d566e
+https://conda.anaconda.org/conda-forge/noarch/soupsieve-2.5-pyhd8ed1ab_1.conda#3f144b2c34f8cb5a9abd9ed23a39c561
 https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-jsmath-1.0.1-pyhd8ed1ab_0.conda#da1d979339e2714c30a8e806a33ec087
 https://conda.anaconda.org/conda-forge/linux-64/tbb-2021.12.0-h00ab1b0_0.conda#f1b776cff1b426e7e7461a8502a3b731
 https://conda.anaconda.org/conda-forge/noarch/tenacity-8.3.0-pyhd8ed1ab_0.conda#216cfa8e32bcd1447646768351df6059
@@ -173,7 +174,9 @@ https://conda.anaconda.org/conda-forge/linux-64/xkeyboard-config-2.41-hd590300_0
 https://conda.anaconda.org/conda-forge/linux-64/xorg-libxext-1.3.4-h0b41bf4_2.conda#82b6df12252e6f32402b96dacc656fec
 https://conda.anaconda.org/conda-forge/linux-64/xorg-libxrender-0.9.11-hd590300_0.conda#ed67c36f215b310412b2af935bf3e530
 https://conda.anaconda.org/conda-forge/noarch/zipp-3.17.0-pyhd8ed1ab_0.conda#2e4d6bc0b14e10f895fc6791a7d9b26a
+https://conda.anaconda.org/conda-forge/noarch/accessible-pygments-0.0.4-pyhd8ed1ab_0.conda#46a2e6e3dfa718ce3492018d5a110dd6
 https://conda.anaconda.org/conda-forge/noarch/babel-2.14.0-pyhd8ed1ab_0.conda#9669586875baeced8fc30c0826c3270e
+https://conda.anaconda.org/conda-forge/noarch/beautifulsoup4-4.12.3-pyha770c72_0.conda#332493000404d8411859539a5a630865
 https://conda.anaconda.org/conda-forge/linux-64/cairo-1.18.0-h3faef2a_0.conda#f907bb958910dc404647326ca80c263e
 https://conda.anaconda.org/conda-forge/linux-64/cxx-compiler-1.7.0-h00ab1b0_1.conda#28de2e073db9ca9b72858bee9fb6f571
 https://conda.anaconda.org/conda-forge/linux-64/cytoolz-0.12.3-py39hd1e30aa_0.conda#dc0fb8e157c7caba4c98f1e1f9d2e5f4
@@ -196,6 +199,7 @@ https://conda.anaconda.org/conda-forge/noarch/pyproject-metadata-0.8.0-pyhd8ed1a
 https://conda.anaconda.org/conda-forge/noarch/pytest-7.4.4-pyhd8ed1ab_0.conda#a9d145de8c5f064b5fa68fb34725d9f4
 https://conda.anaconda.org/conda-forge/noarch/python-dateutil-2.9.0-pyhd8ed1ab_0.conda#2cf4264fffb9e6eff6031c5b6884d61c
 https://conda.anaconda.org/conda-forge/linux-64/sip-6.7.12-py39h3d6467e_0.conda#e667a3ab0df62c54e60e1843d2e6defb
+https://conda.anaconda.org/conda-forge/noarch/typing-extensions-4.11.0-hd8ed1ab_0.conda#471e3988f8ca5e9eb3ce6be7eac3bcee
 https://conda.anaconda.org/conda-forge/noarch/urllib3-2.2.1-pyhd8ed1ab_0.conda#08807a87fa7af10754d46f63b368e016
 https://conda.anaconda.org/conda-forge/linux-64/compilers-1.7.0-ha770c72_1.conda#d8d07866ac3b5b6937213c89a1874f08
 https://conda.anaconda.org/conda-forge/linux-64/gstreamer-1.24.3-haf2f30d_0.conda#f3df87cc9ef0b5113bff55aefcbcafd5
@@ -212,7 +216,7 @@ https://conda.anaconda.org/conda-forge/noarch/dask-core-2024.5.0-pyhd8ed1ab_0.co
 https://conda.anaconda.org/conda-forge/linux-64/gst-plugins-base-1.24.3-h9ad1361_0.conda#8fb0e954c616bb0f9389efac4b4ed44b
 https://conda.anaconda.org/conda-forge/linux-64/libcblas-3.9.0-22_linux64_mkl.conda#d6f942423116553f068b2f2d93ffea2e
 https://conda.anaconda.org/conda-forge/linux-64/liblapack-3.9.0-22_linux64_mkl.conda#4edf2e7ce63920e4f539d12e32fb478e
-https://conda.anaconda.org/conda-forge/noarch/pooch-1.8.1-pyhd8ed1ab_0.conda#d15917f33140f8d2ac9ca44db7ec8a25
+https://conda.anaconda.org/conda-forge/noarch/pooch-1.6.0-pyhd8ed1ab_0.tar.bz2#6429e1d1091c51f626b5dcfdd38bf429
 https://conda.anaconda.org/conda-forge/linux-64/pulseaudio-client-17.0-hb77b528_0.conda#07f45f1be1c25345faddb8db0de8039b
 https://conda.anaconda.org/conda-forge/linux-64/liblapacke-3.9.0-22_linux64_mkl.conda#aa0a5a70e1c957d5911e76ac98e471e1
 https://conda.anaconda.org/conda-forge/linux-64/numpy-1.19.5-py39hd249d9e_3.tar.bz2#0cf333996ebdeeba8d1c8c1c0ee9eff9
@@ -236,13 +240,18 @@ https://conda.anaconda.org/conda-forge/noarch/tifffile-2020.6.3-py_0.tar.bz2#1fb
 https://conda.anaconda.org/conda-forge/linux-64/scikit-image-0.17.2-py39hde0f152_4.tar.bz2#2a58a7e382317b03f023b2fddf40f8a1
 https://conda.anaconda.org/conda-forge/noarch/seaborn-0.12.2-hd8ed1ab_0.conda#50847a47c07812f88581081c620f5160
 https://conda.anaconda.org/conda-forge/noarch/numpydoc-1.2-pyhd8ed1ab_0.tar.bz2#025ad7ca2c7f65007ab6b6f5d93a56eb
+https://conda.anaconda.org/conda-forge/noarch/pydata-sphinx-theme-0.15.2-pyhd8ed1ab_0.conda#ce99859070b0e17ccc63234ca58f3ed8
 https://conda.anaconda.org/conda-forge/noarch/sphinx-copybutton-0.5.2-pyhd8ed1ab_0.conda#ac832cc43adc79118cf6e23f1f9b8995
+https://conda.anaconda.org/conda-forge/noarch/sphinx-design-0.5.0-pyhd8ed1ab_0.conda#264b3c697fa9cdade87eb0abe4440d54
 https://conda.anaconda.org/conda-forge/noarch/sphinx-gallery-0.15.0-pyhd8ed1ab_0.conda#1a49ca9515ef9a96edff2eea06143dc6
 https://conda.anaconda.org/conda-forge/noarch/sphinx-prompt-1.3.0-py_0.tar.bz2#9363002e2a134a287af4e32ff0f26cdc
+https://conda.anaconda.org/conda-forge/noarch/sphinx-remove-toctrees-0.0.3-pyhd8ed1ab_0.tar.bz2#f6d4e2188e88cf6929847a850db3b223
 https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-applehelp-1.0.8-pyhd8ed1ab_0.conda#611a35a27914fac3aa37611a6fe40bb5
 https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-devhelp-1.0.6-pyhd8ed1ab_0.conda#d7e4954df0d3aea2eacc7835ad12671d
 https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-htmlhelp-2.0.5-pyhd8ed1ab_0.conda#7e1e7437273682ada2ed5e9e9714b140
 https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-qthelp-1.0.7-pyhd8ed1ab_0.conda#26acae54b06f178681bfb551760f5dd1
 https://conda.anaconda.org/conda-forge/noarch/sphinx-6.0.0-pyhd8ed1ab_2.conda#ac1d3b55da1669ee3a56973054fd7efb
 https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-serializinghtml-1.1.10-pyhd8ed1ab_0.conda#e507335cb4ca9cff4c3d0fa9cdab255e
+# pip libsass @ https://files.pythonhosted.org/packages/fd/5a/eb5b62641df0459a3291fc206cf5bd669c0feed7814dded8edef4ade8512/libsass-0.23.0-cp38-abi3-manylinux_2_5_x86_64.manylinux1_x86_64.whl#sha256=4a218406d605f325d234e4678bd57126a66a88841cb95bee2caeafdc6f138306
+# pip sphinxcontrib-sass @ https://files.pythonhosted.org/packages/2e/87/7c2eb08e3ca1d6baae32c0a5e005330fe1cec93a36aa085e714c3b3a3c7d/sphinxcontrib_sass-0.3.4-py2.py3-none-any.whl#sha256=a0c79a44ae8b8935c02dc340ebe40c9e002c839331201c899dc93708970c355a
 # pip sphinxext-opengraph @ https://files.pythonhosted.org/packages/50/ac/c105ed3e0a00b14b28c0aa630935af858fd8a32affeff19574b16e2c6ae8/sphinxext_opengraph-0.4.2-py3-none-any.whl#sha256=a51f2604f9a5b6c0d25d3a88e694d5c02e20812dc0e482adf96c8628f9109357
diff --git a/build_tools/circle/list_versions.py b/build_tools/circle/list_versions.py
@@ -1,6 +1,11 @@
 #!/usr/bin/env python3
 
-# List all available versions of the documentation
+# Write the available versions page (--rst) and the version switcher JSON (--json).
+# Version switcher see:
+# https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/version-dropdown.html
+# https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/announcements.html#announcement-banners
+
+import argparse
 import json
 import re
 import sys
@@ -52,14 +57,19 @@ def get_file_size(version):
             return human_readable_data_quantity(path_details["size"], 1000)
 
 
-print(":orphan:")
-print()
-heading = "Available documentation for Scikit-learn"
-print(heading)
-print("=" * len(heading))
-print()
-print("Web-based documentation is available for versions listed below:")
-print()
+parser = argparse.ArgumentParser()
+parser.add_argument("--rst", type=str, required=True)
+parser.add_argument("--json", type=str, required=True)
+args = parser.parse_args()
+
+heading = "Available documentation for scikit-learn"
+json_content = []
+rst_content = [
+    ":orphan:\n",
+    heading,
+    "=" * len(heading) + "\n",
+    "Web-based documentation is available for versions listed below:\n",
+]
 
 ROOT_URL = (
     "https://api.github.com/repos/scikit-learn/scikit-learn.github.io/contents/"  # noqa
@@ -93,26 +103,40 @@ def get_file_size(version):
 
 # Output in order: dev, stable, decreasing other version
 seen = set()
-for name in NAMED_DIRS + sorted(
-    (k for k in dirs if k[:1].isdigit()), key=parse_version, reverse=True
+for i, name in enumerate(
+    NAMED_DIRS
+    + sorted((k for k in dirs if k[:1].isdigit()), key=parse_version, reverse=True)
 ):
     version_num, file_size = dirs[name]
     if version_num in seen:
         # symlink came first
         continue
     else:
         seen.add(version_num)
-    name_display = "" if name[:1].isdigit() else " (%s)" % name
-    path = "https://scikit-learn.org/%s/" % name
-    out = "* `Scikit-learn %s%s documentation <%s>`_" % (
-        version_num,
-        name_display,
-        path,
-    )
+
+    full_name = f"{version_num}" if name[:1].isdigit() else f"{version_num} ({name})"
+    path = f"https://scikit-learn.org/{name}/"
+
+    # Update JSON for the version switcher; only keep the 8 latest versions to avoid
+    # overloading the version switcher dropdown
+    if i < 8:
+        info = {"name": full_name, "version": version_num, "url": path}
+        if name == "stable":
+            info["preferred"] = True
+        json_content.append(info)
+
+    # Printout for the historical version page
+    out = f"* `scikit-learn {full_name} documentation <{path}>`_"
     if file_size is not None:
         file_extension = get_file_extension(version_num)
         out += (
             f" (`{file_extension.upper()} {file_size} <{path}/"
             f"_downloads/scikit-learn-docs.{file_extension}>`_)"
         )
-    print(out)
+    rst_content.append(out)
+
+with open(args.rst, "w", encoding="utf-8") as f:
+    f.write("\n".join(rst_content) + "\n")
+
+with open(args.json, "w", encoding="utf-8") as f:
+    json.dump(json_content, f, indent=2)
diff --git a/build_tools/update_environments_and_lock_files.py b/build_tools/update_environments_and_lock_files.py
@@ -307,8 +307,14 @@ def remove_from(alist, to_remove):
             "plotly",
             "polars",
             "pooch",
+            "sphinx-remove-toctrees",
+            "sphinx-design",
+            "pydata-sphinx-theme",
+        ],
+        "pip_dependencies": [
+            "sphinxext-opengraph",
+            "sphinxcontrib-sass",
         ],
-        "pip_dependencies": ["sphinxext-opengraph"],
         "package_constraints": {
             "python": "3.9",
             "numpy": "min",
@@ -325,6 +331,11 @@ def remove_from(alist, to_remove):
             "sphinxext-opengraph": "min",
             "plotly": "min",
             "polars": "min",
+            "pooch": "min",
+            "sphinx-design": "min",
+            "sphinxcontrib-sass": "min",
+            "sphinx-remove-toctrees": "min",
+            "pydata-sphinx-theme": "min",
         },
     },
     {
@@ -349,8 +360,15 @@ def remove_from(alist, to_remove):
             "polars",
             "pooch",
             "sphinxext-opengraph",
+            "sphinx-remove-toctrees",
+            "sphinx-design",
+            "pydata-sphinx-theme",
+        ],
+        "pip_dependencies": [
+            "jupyterlite-sphinx",
+            "jupyterlite-pyodide-kernel",
+            "sphinxcontrib-sass",
         ],
-        "pip_dependencies": ["jupyterlite-sphinx", "jupyterlite-pyodide-kernel"],
         "package_constraints": {
             "python": "3.9",
         },
@@ -426,7 +444,7 @@ def execute_command(command_list):
     )
 
     out, err = proc.communicate()
-    out, err = out.decode(), err.decode()
+    out, err = out.decode(errors="replace"), err.decode(errors="replace")
 
     if proc.returncode != 0:
         command_str = " ".join(command_list)

diff --git a/doc/Makefile b/doc/Makefile
@@ -50,6 +50,8 @@ clean:
 	-rm -rf auto_examples/
 	-rm -rf generated/*
 	-rm -rf modules/generated/
+	-rm -rf css/styles/
+	-rm -rf api/*.rst
 
 # Default to SPHINX_NUMJOBS=1 for full documentation build. Using
 # SPHINX_NUMJOBS!=1 may actually slow down the build, or cause weird issues in