search

sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.55k stars 2.12k forks source link

A class with a `__setattr__` method raising an exception cannot be rendered by Sphinx's autodoc #11986

Open kdeldycke opened 8 months ago

kdeldycke commented 8 months ago

Describe the bug

There is a class called FrozenSpaceMeta from the cloup project that I try to render with Sphinx's autodoc, but it always fails because its __setattr__ method is raising an exception.

Tl;Dr - the following class:

class FrozenSpaceMeta(type):

    def __setattr__(cls, key: str, value: Any) -> None:
        raise Exception("you can't set attributes on this class")

triggers that exception:

(...)
  File "/Users/kde/click-extra/.venv/lib/python3.12/site-packages/sphinx/ext/autodoc/__init__.py", line 824, in document_members
    documenter.generate(
  File "/Users/kde/click-extra/.venv/lib/python3.12/site-packages/sphinx/ext/autodoc/__init__.py", line 879, in generate
    if not self.import_object():
           ^^^^^^^^^^^^^^^^^^^^
  File "/Users/kde/click-extra/.venv/lib/python3.12/site-packages/sphinx/ext/autodoc/__init__.py", line 2575, in import_object
    self.update_annotations(self.parent)
  File "/Users/kde/click-extra/.venv/lib/python3.12/site-packages/sphinx/ext/autodoc/__init__.py", line 2552, in update_annotations
    parent.__annotations__ = annotations
    ^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/kde/click-extra/.venv/lib/python3.12/site-packages/cloup/_util.py", line 129, in __setattr__
    raise Exception("you can't set attributes on this class")
Exception: you can't set attributes on this class

How to Reproduce

This happened in my Click Extra project, in which I re-expose cloup.Color in my click_extra module via __all__.

You can setup the initial project with:

$ git clone https://github.com/kdeldycke/click-extra.git
$ cd click-extra
$ pip install poetry
$ poetry install

And here is the full traceback of Sphinx trying to generate the documentation of Click Extra:

$ poetry run sphinx-build -b html ./docs ./docs/html
# Platform:         darwin; (macOS-14.3.1-arm64-64bit)
# Sphinx version:   7.1.2
# Python version:   3.12.1 (CPython)
# Docutils version: 0.20.1
# Jinja2 version:   3.1.3
# Pygments version: 2.17.2

# Last messages:
#   [config changed ('version')]
#   22 added, 0 changed, 0 removed

#   reading sources... [  5%]
#   changelog
#   

#   reading sources... [  9%]
#   click_extra
#   

# Loaded extensions:
#   sphinx.ext.mathjax (7.1.2)
#   alabaster (0.7.13)
#   sphinxcontrib.applehelp (1.0.4)
#   sphinxcontrib.devhelp (1.0.2)
#   sphinxcontrib.htmlhelp (2.0.1)
#   sphinxcontrib.serializinghtml (1.1.5)
#   sphinxcontrib.qthelp (1.0.3)
#   sphinx.ext.autodoc.preserve_defaults (7.1.2)
#   sphinx.ext.autodoc.type_comment (7.1.2)
#   sphinx.ext.autodoc.typehints (7.1.2)
#   sphinx.ext.autodoc (7.1.2)
#   sphinx.ext.todo (7.1.2)
#   sphinx.ext.extlinks (7.1.2)
#   sphinx.ext.intersphinx (7.1.2)
#   sphinx.ext.viewcode (7.1.2)
#   sphinx_copybutton (0.5.2)
#   sphinx_design (0.5.0)
#   sphinx_issues (4.0.0)
#   sphinxext.opengraph (unknown version)
#   myst_parser (2.0.0)
#   sphinx.ext.autosectionlabel (7.1.2)
#   sphinx_autodoc_typehints (unknown version)
#   click_extra.sphinx (unknown version)
#   sphinxcontrib.mermaid (7.1.2)
#   furo (2024.01.29)
#   sphinx_basic_ng (1.0.0.beta2)

# Traceback:
Traceback (most recent call last):
  File "/Users/kde/click-extra/.venv/lib/python3.12/site-packages/sphinx/cmd/build.py", line 290, in build_main
    app.build(args.force_all, args.filenames)
  File "/Users/kde/click-extra/.venv/lib/python3.12/site-packages/sphinx/application.py", line 351, in build
    self.builder.build_update()
  File "/Users/kde/click-extra/.venv/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 290, in build_update
    self.build(to_build,
  File "/Users/kde/click-extra/.venv/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 310, in build
    updated_docnames = set(self.read())
                           ^^^^^^^^^^^
  File "/Users/kde/click-extra/.venv/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 417, in read
    self._read_serial(docnames)
  File "/Users/kde/click-extra/.venv/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 438, in _read_serial
    self.read_doc(docname)
  File "/Users/kde/click-extra/.venv/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 494, in read_doc
    publisher.publish()
  File "/Users/kde/click-extra/.venv/lib/python3.12/site-packages/docutils/core.py", line 234, in publish
    self.document = self.reader.read(self.source, self.parser,
                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/kde/click-extra/.venv/lib/python3.12/site-packages/sphinx/io.py", line 104, in read
    self.parse()
  File "/Users/kde/click-extra/.venv/lib/python3.12/site-packages/docutils/readers/__init__.py", line 76, in parse
    self.parser.parse(self.input, document)
  File "/Users/kde/click-extra/.venv/lib/python3.12/site-packages/sphinx/parsers.py", line 80, in parse
    self.statemachine.run(inputlines, document, inliner=self.inliner)
  File "/Users/kde/click-extra/.venv/lib/python3.12/site-packages/docutils/parsers/rst/states.py", line 169, in run
    results = StateMachineWS.run(self, input_lines, input_offset,
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/kde/click-extra/.venv/lib/python3.12/site-packages/docutils/statemachine.py", line 233, in run
    context, next_state, result = self.check_line(
                                  ^^^^^^^^^^^^^^^^
  File "/Users/kde/click-extra/.venv/lib/python3.12/site-packages/docutils/statemachine.py", line 445, in check_line
    return method(match, context, next_state)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/kde/click-extra/.venv/lib/python3.12/site-packages/docutils/parsers/rst/states.py", line 2785, in underline
    self.section(title, source, style, lineno - 1, messages)
  File "/Users/kde/click-extra/.venv/lib/python3.12/site-packages/docutils/parsers/rst/states.py", line 325, in section
    self.new_subsection(title, lineno, messages)
  File "/Users/kde/click-extra/.venv/lib/python3.12/site-packages/docutils/parsers/rst/states.py", line 391, in new_subsection
    newabsoffset = self.nested_parse(
                   ^^^^^^^^^^^^^^^^^^
  File "/Users/kde/click-extra/.venv/lib/python3.12/site-packages/docutils/parsers/rst/states.py", line 279, in nested_parse
    state_machine.run(block, input_offset, memo=self.memo,
  File "/Users/kde/click-extra/.venv/lib/python3.12/site-packages/docutils/parsers/rst/states.py", line 195, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/kde/click-extra/.venv/lib/python3.12/site-packages/docutils/statemachine.py", line 233, in run
    context, next_state, result = self.check_line(
                                  ^^^^^^^^^^^^^^^^
  File "/Users/kde/click-extra/.venv/lib/python3.12/site-packages/docutils/statemachine.py", line 445, in check_line
    return method(match, context, next_state)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/kde/click-extra/.venv/lib/python3.12/site-packages/docutils/parsers/rst/states.py", line 2355, in explicit_markup
    nodelist, blank_finish = self.explicit_construct(match)
                             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/kde/click-extra/.venv/lib/python3.12/site-packages/docutils/parsers/rst/states.py", line 2367, in explicit_construct
    return method(self, expmatch)
           ^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/kde/click-extra/.venv/lib/python3.12/site-packages/docutils/parsers/rst/states.py", line 2104, in directive
    return self.run_directive(
           ^^^^^^^^^^^^^^^^^^^
  File "/Users/kde/click-extra/.venv/lib/python3.12/site-packages/docutils/parsers/rst/states.py", line 2154, in run_directive
    result = directive_instance.run()
             ^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/kde/click-extra/.venv/lib/python3.12/site-packages/sphinx/ext/autodoc/directive.py", line 135, in run
    documenter.generate(more_content=self.content)
  File "/Users/kde/click-extra/.venv/lib/python3.12/site-packages/sphinx/ext/autodoc/__init__.py", line 950, in generate
    self.document_members(all_members)
  File "/Users/kde/click-extra/.venv/lib/python3.12/site-packages/sphinx/ext/autodoc/__init__.py", line 824, in document_members
    documenter.generate(
  File "/Users/kde/click-extra/.venv/lib/python3.12/site-packages/sphinx/ext/autodoc/__init__.py", line 1871, in generate
    return super().generate(more_content=more_content,
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/kde/click-extra/.venv/lib/python3.12/site-packages/sphinx/ext/autodoc/__init__.py", line 950, in generate
    self.document_members(all_members)
  File "/Users/kde/click-extra/.venv/lib/python3.12/site-packages/sphinx/ext/autodoc/__init__.py", line 1857, in document_members
    super().document_members(all_members)
  File "/Users/kde/click-extra/.venv/lib/python3.12/site-packages/sphinx/ext/autodoc/__init__.py", line 824, in document_members
    documenter.generate(
  File "/Users/kde/click-extra/.venv/lib/python3.12/site-packages/sphinx/ext/autodoc/__init__.py", line 879, in generate
    if not self.import_object():
           ^^^^^^^^^^^^^^^^^^^^
  File "/Users/kde/click-extra/.venv/lib/python3.12/site-packages/sphinx/ext/autodoc/__init__.py", line 2575, in import_object
    self.update_annotations(self.parent)
  File "/Users/kde/click-extra/.venv/lib/python3.12/site-packages/sphinx/ext/autodoc/__init__.py", line 2552, in update_annotations
    parent.__annotations__ = annotations
    ^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/kde/click-extra/.venv/lib/python3.12/site-packages/cloup/_util.py", line 129, in __setattr__
    raise Exception("you can't set attributes on this class")
Exception: you can't set attributes on this class

Environment Information

Platform:              darwin; (macOS-14.3.1-arm64-64bit)
Python version:        3.12.2 (main, Feb  6 2024, 20:19:44) [Clang 15.0.0 (clang-1500.1.0.2.5)])
Python implementation: CPython
Sphinx version:        7.1.2
Docutils version:      0.20.1
Jinja2 version:        3.1.3
Pygments version:      2.17.2

Sphinx extensions

extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.todo",
    "sphinx.ext.intersphinx",
    "sphinx.ext.viewcode",
    "sphinx_copybutton",
    "sphinx_design",
    "sphinx_issues",
    "sphinxext.opengraph",
    "myst_parser",
    "sphinx.ext.autosectionlabel",
    "sphinx_autodoc_typehints",
    "click_extra.sphinx",
    "sphinxcontrib.mermaid",
]

Additional context

This has been originally reported at: https://github.com/janluke/cloup/issues/177

picnixz commented 8 months ago

Well.. it's probably easy to fix on our side by simply having a try-except block but then it'll be difficult to autodoc-it.