Python match/case statement does not build GitHub page

[FiorinaLi]

Problem

We run into a build error when including a function alike the one below in one of our modules that forms the API; we believe the problem stems from the match-case code chunk.

Example function

Specifically, we specify a function as follows:

  def get_iate(rng, x_np, iate_type, no_effect = False):
      """Compute IATE."""
      
      cols = x_np.shape[1]
      coeff, _, _ = coefficients(rng, cols)
      index = (x_np @ coeff).reshape(-1, 1)
  
      match iate_type:
          case 'linear':
              iate = index
      iate = 1
      if no_effect:
          iate *= 0
  
      return iate

Sphinx requirements

Our documentation relies on Sphinx with the current requirements:

sphinx==5.0.2
Pygments>=2.7.0
pydata-sphinx-theme==0.14.4
sphinx-copybutton
numpy
pandas
scipy
scikit-learn
statsmodels
plotly
matplotlib
sphinx_design

or you can also access the configuration file under this link.

Would you have any suggestions on how to proceed or solve the problem?

[AA-Turner]

You are running a very old version of Sphinx. We only provide free support for running with the latest release (v9).

Please could you paste the logs you get from running, including any errors or warnings?

A

[FiorinaLi]

Thanks for the quick response! I’ve attached the full Sphinx build logs below.

If we’re not able to identify a clear root cause from the logs, do you have any guidance on how to upgrade to the latest Sphinx release while minimizing dependency conflicts?

Happy to provide any additional diagnostics if needed.

Logs

Run ammaraskar/sphinx-action@master
/usr/bin/docker run --name c2c75c78cef3b201649d8a9d098037d0f47df_0f5f5f --label 4c2c75 --workdir /github/workspace --rm -e "pythonLocation" -e "PKG_CONFIG_PATH" -e "Python_ROOT_DIR" -e "Python2_ROOT_DIR" -e "Python3_ROOT_DIR" -e "LD_LIBRARY_PATH" -e "INPUT_DOCS-FOLDER" -e "INPUT_BUILD-COMMAND" -e "INPUT_PRE-BUILD-COMMAND" -e "HOME" -e "GITHUB_JOB" -e "GITHUB_REF" -e "GITHUB_SHA" -e "GITHUB_REPOSITORY" -e "GITHUB_REPOSITORY_OWNER" -e "GITHUB_REPOSITORY_OWNER_ID" -e "GITHUB_RUN_ID" -e "GITHUB_RUN_NUMBER" -e "GITHUB_RETENTION_DAYS" -e "GITHUB_RUN_ATTEMPT" -e "GITHUB_ACTOR_ID" -e "GITHUB_ACTOR" -e "GITHUB_WORKFLOW" -e "GITHUB_HEAD_REF" -e "GITHUB_BASE_REF" -e "GITHUB_EVENT_NAME" -e "GITHUB_SERVER_URL" -e "GITHUB_API_URL" -e "GITHUB_GRAPHQL_URL" -e "GITHUB_REF_NAME" -e "GITHUB_REF_PROTECTED" -e "GITHUB_REF_TYPE" -e "GITHUB_WORKFLOW_REF" -e "GITHUB_WORKFLOW_SHA" -e "GITHUB_REPOSITORY_ID" -e "GITHUB_TRIGGERING_ACTOR" -e "GITHUB_WORKSPACE" -e "GITHUB_ACTION" -e "GITHUB_EVENT_PATH" -e "GITHUB_ACTION_REPOSITORY" -e "GITHUB_ACTION_REF" -e "GITHUB_PATH" -e "GITHUB_ENV" -e "GITHUB_STEP_SUMMARY" -e "GITHUB_STATE" -e "GITHUB_OUTPUT" -e "RUNNER_OS" -e "RUNNER_ARCH" -e "RUNNER_NAME" -e "RUNNER_ENVIRONMENT" -e "RUNNER_TOOL_CACHE" -e "RUNNER_TEMP" -e "RUNNER_WORKSPACE" -e "ACTIONS_RUNTIME_URL" -e "ACTIONS_RUNTIME_TOKEN" -e "ACTIONS_CACHE_URL" -e "ACTIONS_RESULTS_URL" -e GITHUB_ACTIONS=true -e CI=true -v "/var/run/docker.sock":"/var/run/docker.sock" -v "/home/runner/work/_temp":"/github/runner_temp" -v "/home/runner/work/_temp/_github_home":"/github/home" -v "/home/runner/work/_temp/_github_workflow":"/github/workflow" -v "/home/runner/work/_temp/_runner_file_commands":"/github/file_commands" -v "/home/runner/work/mcf/mcf":"/github/workspace" 4c2c75:c78cef3b201649d8a9d098037d0f47df
WARNING: The directory '/github/home/.cache/pip' or its parent directory is not owned or is not writable by the current user. The cache has been disabled. Check the permissions and owner of that directory. If executing pip with sudo, you may want sudo's -H flag.
Collecting sphinx==5.0.2
  Downloading Sphinx-5.0.2-py3-none-any.whl (3.1 MB)
Collecting Pygments>=2.7.0
  Downloading pygments-2.19.2-py3-none-any.whl (1.2 MB)
Collecting pydata-sphinx-theme==0.14.4
  Downloading pydata_sphinx_theme-0.14.4-py3-none-any.whl (4.7 MB)
Collecting sphinx-copybutton
  Downloading sphinx_copybutton-0.5.2-py3-none-any.whl (13 kB)
Collecting numpy
  Downloading numpy-1.24.4-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (17.3 MB)
Collecting pandas
  Downloading pandas-2.0.3-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (12.4 MB)
Collecting scipy
  Downloading scipy-1.10.1-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (34.5 MB)
Collecting scikit-learn
  Downloading scikit_learn-1.3.2-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (11.1 MB)
Collecting statsmodels
  Downloading statsmodels-0.14.1-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (10.9 MB)
Collecting plotly
  Downloading plotly-6.5.0-py3-none-any.whl (9.9 MB)
Collecting matplotlib
  Downloading matplotlib-3.7.5-cp38-cp38-manylinux_2_12_x86_64.manylinux2010_x86_64.whl (9.2 MB)
Collecting sphinx_design
  Downloading sphinx_design-0.5.0-py3-none-any.whl (2.2 MB)
Collecting myst-parser
  Downloading myst_parser-3.0.1-py3-none-any.whl (83 kB)
Collecting ray
  Downloading ray-2.10.0-cp38-cp38-manylinux2014_x86_64.whl (65.2 MB)
Collecting packaging>=21.3
  Downloading packaging-25.0-py3-none-any.whl (66 kB)
Requirement already satisfied: sphinxcontrib-devhelp in /usr/local/lib/python3.8/site-packages (from sphinx==5.0.2->-r docs/requirements.txt (line 1)) (1.0.2)
Requirement already satisfied: sphinxcontrib-jsmath in /usr/local/lib/python3.8/site-packages (from sphinx==5.0.2->-r docs/requirements.txt (line 1)) (1.0.1)
Requirement already satisfied: imagesize in /usr/local/lib/python3.8/site-packages (from sphinx==5.0.2->-r docs/requirements.txt (line 1)) (1.2.0)
Requirement already satisfied: docutils<0.19,>=0.14 in /usr/local/lib/python3.8/site-packages (from sphinx==5.0.2->-r docs/requirements.txt (line 1)) (0.16)
Requirement already satisfied: sphinxcontrib-qthelp in /usr/local/lib/python3.8/site-packages (from sphinx==5.0.2->-r docs/requirements.txt (line 1)) (1.0.3)
Requirement already satisfied: babel>=1.3 in /usr/local/lib/python3.8/site-packages (from sphinx==5.0.2->-r docs/requirements.txt (line 1)) (2.8.0)
Collecting importlib-metadata>=4.4; python_version < "3.10"
  Downloading importlib_metadata-8.5.0-py3-none-any.whl (26 kB)
Requirement already satisfied: requests>=2.5.0 in /usr/local/lib/python3.8/site-packages (from sphinx==5.0.2->-r docs/requirements.txt (line 1)) (2.23.0)
Collecting sphinxcontrib-serializinghtml>=1.1.5
  Downloading sphinxcontrib_serializinghtml-1.1.5-py2.py3-none-any.whl (94 kB)
Requirement already satisfied: snowballstemmer>=1.1 in /usr/local/lib/python3.8/site-packages (from sphinx==5.0.2->-r docs/requirements.txt (line 1)) (2.0.0)
Requirement already satisfied: alabaster<0.8,>=0.7 in /usr/local/lib/python3.8/site-packages (from sphinx==5.0.2->-r docs/requirements.txt (line 1)) (0.7.12)
Requirement already satisfied: sphinxcontrib-applehelp in /usr/local/lib/python3.8/site-packages (from sphinx==5.0.2->-r docs/requirements.txt (line 1)) (1.0.2)
Requirement already satisfied: Jinja2>=2.3 in /usr/local/lib/python3.8/site-packages (from sphinx==5.0.2->-r docs/requirements.txt (line 1)) (2.11.1)
Collecting sphinxcontrib-htmlhelp>=2.0.0
  Downloading sphinxcontrib_htmlhelp-2.0.1-py3-none-any.whl (99 kB)
Collecting accessible-pygments
  Downloading accessible_pygments-0.0.4-py2.py3-none-any.whl (29 kB)
Collecting beautifulsoup4
  Downloading beautifulsoup4-4.14.3-py3-none-any.whl (107 kB)
Collecting typing-extensions
  Downloading typing_extensions-4.13.2-py3-none-any.whl (45 kB)
Collecting tzdata>=2022.1
  Downloading tzdata-2025.2-py2.py3-none-any.whl (347 kB)
Collecting python-dateutil>=2.8.2
  Downloading python_dateutil-2.9.0.post0-py2.py3-none-any.whl (229 kB)
Collecting pytz>=2020.1
  Downloading pytz-2025.2-py2.py3-none-any.whl (509 kB)
Collecting joblib>=1.1.1
  Downloading joblib-1.4.2-py3-none-any.whl (301 kB)
Collecting threadpoolctl>=2.0.0
  Downloading threadpoolctl-3.5.0-py3-none-any.whl (18 kB)
Collecting patsy>=0.5.4
  Downloading patsy-1.0.2-py2.py3-none-any.whl (233 kB)
Collecting narwhals>=1.15.1
  Downloading narwhals-1.42.1-py3-none-any.whl (359 kB)
Requirement already satisfied: pyparsing>=2.3.1 in /usr/local/lib/python3.8/site-packages (from matplotlib->-r docs/requirements.txt (line 11)) (2.4.6)
Collecting kiwisolver>=1.0.1
  Downloading kiwisolver-1.4.7-cp38-cp38-manylinux_2_5_x86_64.manylinux1_x86_64.whl (1.2 MB)
Collecting importlib-resources>=3.2.0; python_version < "3.10"
  Downloading importlib_resources-6.4.5-py3-none-any.whl (36 kB)
Collecting cycler>=0.10
  Downloading cycler-0.12.1-py3-none-any.whl (8.3 kB)
Collecting fonttools>=4.22.0
  Downloading fonttools-4.57.0-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (4.7 MB)
Collecting contourpy>=1.0.1
  Downloading contourpy-1.1.1-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (301 kB)
Requirement already satisfied: pillow>=6.2.0 in /usr/local/lib/python3.8/site-packages (from matplotlib->-r docs/requirements.txt (line 11)) (7.0.0)
Collecting pyyaml
  Downloading PyYAML-6.0.3-cp38-cp38-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (806 kB)
Collecting mdit-py-plugins~=0.4
  Downloading mdit_py_plugins-0.4.2-py3-none-any.whl (55 kB)
Collecting markdown-it-py~=3.0
  Downloading markdown_it_py-3.0.0-py3-none-any.whl (87 kB)
Collecting frozenlist
  Downloading frozenlist-1.5.0-cp38-cp38-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl (243 kB)
Collecting click>=7.0
  Downloading click-8.1.8-py3-none-any.whl (98 kB)
Collecting filelock
  Downloading filelock-3.16.1-py3-none-any.whl (16 kB)
Collecting msgpack<2.0.0,>=1.0.0
  Downloading msgpack-1.1.1-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (413 kB)
Collecting protobuf!=3.19.5,>=3.15.3
  Downloading protobuf-5.29.5-cp38-abi3-manylinux2014_x86_64.whl (319 kB)
Collecting aiosignal
  Downloading aiosignal-1.3.1-py3-none-any.whl (7.6 kB)
Collecting jsonschema
  Downloading jsonschema-4.23.0-py3-none-any.whl (88 kB)
Collecting zipp>=3.20
  Downloading zipp-3.20.2-py3-none-any.whl (9.2 kB)
Requirement already satisfied: idna<3,>=2.5 in /usr/local/lib/python3.8/site-packages (from requests>=2.5.0->sphinx==5.0.2->-r docs/requirements.txt (line 1)) (2.9)
Requirement already satisfied: urllib3!=1.25.0,!=1.25.1,<1.26,>=1.21.1 in /usr/local/lib/python3.8/site-packages (from requests>=2.5.0->sphinx==5.0.2->-r docs/requirements.txt (line 1)) (1.25.8)
Requirement already satisfied: chardet<4,>=3.0.2 in /usr/local/lib/python3.8/site-packages (from requests>=2.5.0->sphinx==5.0.2->-r docs/requirements.txt (line 1)) (3.0.4)
Requirement already satisfied: certifi>=2017.4.17 in /usr/local/lib/python3.8/site-packages (from requests>=2.5.0->sphinx==5.0.2->-r docs/requirements.txt (line 1)) (2019.11.28)
Requirement already satisfied: MarkupSafe>=0.23 in /usr/local/lib/python3.8/site-packages (from Jinja2>=2.3->sphinx==5.0.2->-r docs/requirements.txt (line 1)) (1.1.1)
Collecting soupsieve>=1.6.1
  Downloading soupsieve-2.7-py3-none-any.whl (36 kB)
Requirement already satisfied: six>=1.5 in /usr/local/lib/python3.8/site-packages (from python-dateutil>=2.8.2->pandas->-r docs/requirements.txt (line 6)) (1.14.0)
Collecting mdurl~=0.1
  Downloading mdurl-0.1.2-py3-none-any.whl (10.0 kB)
Collecting jsonschema-specifications>=2023.03.6
  Downloading jsonschema_specifications-2023.12.1-py3-none-any.whl (18 kB)
Collecting referencing>=0.28.4
  Downloading referencing-0.35.1-py3-none-any.whl (26 kB)
Collecting attrs>=22.2.0
  Downloading attrs-25.3.0-py3-none-any.whl (63 kB)
Collecting pkgutil-resolve-name>=1.3.10; python_version < "3.9"
  Downloading pkgutil_resolve_name-1.3.10-py3-none-any.whl (4.7 kB)
Collecting rpds-py>=0.7.1
  Downloading rpds_py-0.20.1-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (360 kB)
ERROR: myst-parser 3.0.1 has requirement docutils<0.22,>=0.18, but you'll have docutils 0.16 which is incompatible.
ERROR: myst-parser 3.0.1 has requirement sphinx<8,>=6, but you'll have sphinx 5.0.2 which is incompatible.
Installing collected packages: packaging, Pygments, zipp, importlib-metadata, sphinxcontrib-serializinghtml, sphinxcontrib-htmlhelp, sphinx, accessible-pygments, soupsieve, typing-extensions, beautifulsoup4, pydata-sphinx-theme, sphinx-copybutton, numpy, tzdata, python-dateutil, pytz, pandas, scipy, joblib, threadpoolctl, scikit-learn, patsy, statsmodels, narwhals, plotly, kiwisolver, importlib-resources, cycler, fonttools, contourpy, matplotlib, sphinx-design, pyyaml, mdurl, markdown-it-py, mdit-py-plugins, myst-parser, frozenlist, click, filelock, msgpack, protobuf, aiosignal, rpds-py, attrs, referencing, jsonschema-specifications, pkgutil-resolve-name, jsonschema, ray
  Attempting uninstall: packaging
    Found existing installation: packaging 20.3
    Uninstalling packaging-20.3:
      Successfully uninstalled packaging-20.3
  Attempting uninstall: Pygments
    Found existing installation: Pygments 2.5.2
    Uninstalling Pygments-2.5.2:
      Successfully uninstalled Pygments-2.5.2
  Attempting uninstall: sphinxcontrib-serializinghtml
    Found existing installation: sphinxcontrib-serializinghtml 1.1.4
    Uninstalling sphinxcontrib-serializinghtml-1.1.4:
      Successfully uninstalled sphinxcontrib-serializinghtml-1.1.4
  Attempting uninstall: sphinxcontrib-htmlhelp
    Found existing installation: sphinxcontrib-htmlhelp 1.0.3
    Uninstalling sphinxcontrib-htmlhelp-1.0.3:
      Successfully uninstalled sphinxcontrib-htmlhelp-1.0.3
  Attempting uninstall: sphinx
    Found existing installation: Sphinx 2.4.4
    Uninstalling Sphinx-2.4.4:
      Successfully uninstalled Sphinx-2.4.4
  Attempting uninstall: pytz
    Found existing installation: pytz 2019.3
    Uninstalling pytz-2019.3:
      Successfully uninstalled pytz-2019.3
Successfully installed Pygments-2.19.2 accessible-pygments-0.0.4 aiosignal-1.3.1 attrs-25.3.0 beautifulsoup4-4.14.3 click-8.1.8 contourpy-1.1.1 cycler-0.12.1 filelock-3.16.1 fonttools-4.57.0 frozenlist-1.5.0 importlib-metadata-8.5.0 importlib-resources-6.4.5 joblib-1.4.2 jsonschema-4.23.0 jsonschema-specifications-2023.12.1 kiwisolver-1.4.7 markdown-it-py-3.0.0 matplotlib-3.7.5 mdit-py-plugins-0.4.2 mdurl-0.1.2 msgpack-1.1.1 myst-parser-3.0.1 narwhals-1.42.1 numpy-1.24.4 packaging-25.0 pandas-2.0.3 patsy-1.0.2 pkgutil-resolve-name-1.3.10 plotly-6.5.0 protobuf-5.29.5 pydata-sphinx-theme-0.14.4 python-dateutil-2.9.0.post0 pytz-2025.2 pyyaml-6.0.3 ray-2.10.0 referencing-0.35.1 rpds-py-0.20.1 scikit-learn-1.3.2 scipy-1.10.1 soupsieve-2.7 sphinx-5.0.2 sphinx-copybutton-0.5.2 sphinx-design-0.5.0 sphinxcontrib-htmlhelp-2.0.1 sphinxcontrib-serializinghtml-1.1.5 statsmodels-0.14.1 threadpoolctl-3.5.0 typing-extensions-4.13.2 tzdata-2025.2 zipp-3.20.2
WARNING: You are using pip version 20.0.2; however, version 25.0.1 is available.
You should consider upgrading via the '/usr/local/bin/python -m pip install --upgrade pip' command.
Running Sphinx v5.0.2
loading pickled environment... failed
failed: source directory has changed
[autosummary] generating autosummary for: FAQ.rst, algorithm_reference.rst, algorithm_reference/QIATEs.rst, algorithm_reference/bgates_cbgates.rst, algorithm_reference/fairscores.rst, algorithm_reference/inference.rst, algorithm_reference/local_centering.rst, algorithm_reference/optimal-policy_algorithm.rst, algorithm_reference/training.rst, changelog.rst, ..., user_guide.rst, user_guide/common_support.rst, user_guide/computational_speed.rst, user_guide/data_cleaning.rst, user_guide/estimation.rst, user_guide/experimental_features.rst, user_guide/feature_selection.rst, user_guide/optimal-policy_example.rst, user_guide/post_estimation_diagnostics.rst, user_guide/weights_clusters.rst

Extension error (sphinx.ext.autosummary):
Handler <function process_generate_options at 0x7f86a0e0b550> for event 'builder-inited' threw an exception (exception: no module named example_data_functions)
make: *** [Makefile:20: html] Error 2
[sphinx-action] Starting sphinx-action build.
Running: 
====================================
Building docs in docs/
====================================
[sphinx-action] Running: ['make', 'html', '-e']
[sphinx-action] Build failed with 0 warnings
Traceback (most recent call last):
  File "/entrypoint.py", line 22, in <module>
    action.build_all_docs(github_env, [os.environ.get("INPUT_DOCS-FOLDER")])
  File "/sphinx_action/action.py", line 167, in build_all_docs
    raise RuntimeError("Build failed")
RuntimeError: Build failed

[AA-Turner]

If we’re not able to identify a clear root cause from the logs, do you have any guidance on how to upgrade to the latest Sphinx release while minimizing dependency conflicts?

pip install -U "Sphinx>=9". Please upgrade Sphinx & then paste the new logs.

A

[FiorinaLi]

We managed to resolve the problem by updating Sphinx and related dependencies to the following:

sphinx>=8
pygments>=2.15
pydata-sphinx-theme>=0.15.3
sphinx-copybutton
numpy
pandas
scipy
scikit-learn
statsmodels
plotly
matplotlib
myst-parser
ray
sphinx_design
packaging>=21.3

Also, changing

       - name: Build HTML
          uses: ammaraskar/sphinx-action@master

to

    - name: Build HTML
       run: sphinx-build -b html docs/source docs/build/html

in the actions workflow was necessary.

Thank you for your support!