sphinx-doc / sphinx-doc/sphinx

Autodoc fails on enums containing special characters

Open
#10,322 4 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

extensions:autodoc type:bug
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

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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.