readthedocs: Add search ranking and use latest Python version (#242)

* readthedocs: Add search ranking and use latest Python version

Add a ranking which search results should pop up first (proposed docs/source > ema_workbench/examples > ema_workbench > everything else > all models).

See https://docs.readthedocs.io/en/stable/config-file/v2.html#search

Also always use latest stable Python version.

* docs: sphinx-rtd-theme as optional dep, specify needs_sphinx

- Set sphinx-rtd-theme as optional docs dependency
- Specify needs_sphinx and needs_extensions in the conf.py configuration file (see https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-needs_sphinx)

* Update .readthedocs.yaml

Try something else to set the docs requirements

* Update .readthedocs.yaml

* readthedocs-sphinx-ext update

* Attempt to fix search by using requirements.txt

* Add general requirements to docs

* docs: conf.py: Implement search workaround

Implement a workaround to get search working again

readthedocs/sphinx_rtd_theme#1452 (comment)

---------

Co-authored-by: Jan Kwakkel <j.h.kwakkel@tudelft.nl>

.readthedocs.yaml

@@ -9,7 +9,7 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.10"
+    python: "3"
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
@@ -18,11 +18,22 @@ sphinx:
 # If using Sphinx, optionally build your docs in additional formats such as PDF
 formats:
   - pdf
+  - htmlzip
 
 # Optionally declare the Python requirements required to build your docs
 python:
-  install:
-    - method: pip
-      path: .
-      extra_requirements:
-        - docs
+   install:
+   - requirements: docs/requirements.txt
+
+# Settings for more control over Server side search.
+# https://docs.readthedocs.io/en/stable/config-file/v2.html#search
+search:
+  # Define which files pop up higher in the search results
+  ranking:
+    'docs/source/': 3
+    'ema_workbench/**': 2
+    'ema_workbench/examples/*': 1
+    '**/models/*': -1
+
+  # Exclude some files from the search
+  ignore: ['MANIFEST.in', '.gitattributes', '**/.gitignore', '**/data/*', '.eggs/**']

docs/requirements.txt

@@ -0,0 +1,19 @@
+# Docs requirements
+sphinx>=6
+sphinx_rtd_theme>=1.2
+readthedocs-sphinx-search>=0.3
+nbsphinx
+myst
+pyscaffold
+myst-parser
+
+# General requirements
+numpy
+pandas
+scikit-learn
+salib>=1.4.6
+platypus-opt
+matplotlib
+statsmodels
+seaborn
+tqdm

docs/source/conf.py

@@ -34,7 +34,8 @@
 # -- General configuration
 
 # If your documentation needs a minimal Sphinx version, state it here.
-# needs_sphinx = '1.3'
+needs_sphinx = "6.0"
+needs_extensions = {"sphinx_rtd_theme": "1.0"}
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
@@ -43,6 +44,7 @@
     "sphinx.ext.doctest",
     "sphinx.ext.napoleon",
     "sphinx.ext.mathjax",
+    "sphinxcontrib.jquery",
     "nbsphinx",
     "myst_parser",
 ]

pyproject.toml

@@ -36,7 +36,7 @@ all = ["ema_workbench[jupyter,dev,cov,docs,graph,parallel]"]
 jupyter = ["jupyter", "jupyter_client", "ipython", "ipykernel"]
 dev = ["pytest", "pytest-mock", "jupyter_client", "ipyparallel"]
 cov = ["pytest-cov", "coverage", "coveralls"]
-docs = ["sphinx", "nbsphinx", "myst", "pyscaffold", "myst-parser"]
+docs = ["sphinx", "sphinx-rtd-theme", "readthedocs-sphinx-search", "nbsphinx", "myst", "pyscaffold", "myst-parser"]
 graph = ["altair", "pydot", "graphviz"]
 parallel = ["ipyparallel", "traitlets"]