sphinx-doc / sphinx-doc/sphinx
Autodoc fails on enums containing special characters
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
Consider the following enum:
Colorspace = Enum("Colorspace", "RGB RGBA L LA 1 CMYK CMYK;I P PA")
Autodoc'ing this enum will yield the following error:
WARNING: invalid signature for autoattribute ('Colorspace.CMYK;I')
WARNING: don't know which module to import for autodocumenting 'Colorspace.CMYK;I' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
It looks like autodoc may be unable to handle enum attributes containing the ; character.
(In Python, the attribute can be accessed by indexing: Colorspace['CMYK;I'])
How to Reproduce
(see the description)
Expected behavior
It should be possible to document enum attributes containing a semicolon character (;). Respectively any character that is not compatible with dotted access but valid in other notations (e.g. getitem indexing).
Your project
private, sorry
Screenshots
No response
OS
Linux Ubuntu 20.04
Python version
3.8.10
Sphinx version
4.5.0
Sphinx extensions
sphinx.ext.autodoc
Extra tools
No response
Additional context
No response
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
Start in the sphinx.ext.autodoc entry point and reproduce the issue with the provided Colorspace enum containing “CMYK;I”. Trace how autodoc parses and resolves enum attributes, then verify that names valid through getitem access are documented without invalid-signature or import warnings.
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
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 68/100