sphinx-doc / sphinx-doc/sphinx

autosummary fails and does not read modules

Open
#14,166 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

extensions:autosummary type:bug
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

Describe the bug

When building the documentation for our python package (https://mcfpy.github.io/mcf/) using Sphinx (sphinx-build -b html docs/source docs/build/html), the build fails during the builder-inited event with the following error:

ExtensionError: Handler <function process_generate_options at ...> for event 'builder-inited' threw an exception 
(exception: no module named optpolicy_main.OptimalPolicy)

This issue occurs even though the same configuration worked with earlier Sphinx versions. The failure happens before page generation, at the autosummary pre-processing step.

The failing import refers to the class:

class OptimalPolicy:
    ...

which is part of the public API and previously built without issues.

How to Reproduce

minimal index.rst:

License
-------

**mcf** is distributed under the `MIT License <https://github.com/MCFpy/mcf?tab=MIT-1-ov-file#readme>`__.

.. toctree::
   :hidden:

   getting_started.rst
   user_guide.rst
   algorithm_reference.rst
   python_api.rst
   FAQ.rst
   changelog.rst

Module that is not parsing with autosummary :
optpolicy_main.py

Environment Information
Run sphinx-build -b html docs/source docs/build/html
Running Sphinx v8.2.3
loading translations [en]... done
Converting `source_suffix = ['.rst', '.md']` to `source_suffix = {'.rst': 'restructuredtext', '.md': 'restructuredtext'}`.
[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)!

Versions
========

* Platform:         linux; (Linux-6.11.0-1018-azure-x86_64-with-glibc2.39)
* Python version:   3.12.12 (CPython)
* Sphinx version:   8.2.3
* Docutils version: 0.21.2
* Jinja2 version:   3.1.6
* Pygments version: 2.19.2

Last Messages
=============

None.

Loaded Extensions
=================

None.

Traceback
=========

      File "/opt/hostedtoolcache/Python/3.12.12/x64/lib/python3.12/site-packages/sphinx/events.py", line 415, in emit
        raise ExtensionError(
    sphinx.errors.ExtensionError: Handler <function process_generate_options at 0x7fbc6ecb84a0> for event 'builder-inited' threw an exception (exception: no module named optpolicy_main.OptimalPolicy)


The full traceback has been saved in:
/tmp/sphinx-err-66l48k9j.log

To report this error to the developers, please open an issue at <https://github.com/sphinx-doc/sphinx/issues/>. Thanks!
Please also report this if it was a user error, so that a better error message can be provided next time.
Error: Process completed with exit code 2.
Sphinx extensions
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.autosummary',
    'sphinx.ext.coverage',
    'sphinx.ext.intersphinx',
    'sphinx.ext.mathjax',
    'sphinx.ext.napoleon',
    'sphinx_copybutton',
    'sphinx.ext.githubpages',
    'sphinx.ext.doctest',
    'sphinx_design', 
    'myst_parser' 
]
Additional context

This is the link to github: https://github.com/MCFpy/mcf

conf.py:
conf.py

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Reproduce with sphinx-build -b html docs/source docs/build/html and inspect the sphinx.ext.autosummary process_generate_options entry point, using mcf/optpolicy_main.py and the linked conf.py as the case study. Compare how the OptimalPolicy reference is resolved and verify that autosummary completes while reading the module and generating its documentation.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.