sphinx-doc / sphinx-doc/sphinx
autosummary fails and does not read modules
Nobody has claimed this yet.
- 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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