sphinx-doc / sphinx-doc/sphinx
Some nested attribute names are stripped
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
Nested trees of py:attribute:: display unintuitively. It appears that every first attribute at an odd depth has most of its name stripped. I believe this is due to this line stripping away the "classname". I have only tested this with HTML generation, but I believe it will affect all other types too since it's a problem with the underlying node tree.
There is a workaround, and that is to duplicate the stripped part of the name so when it gets removed the full name is left (e.g. a.b.c --> a.a.b.c, a.b.c.d.e --> a.b.c.a.b.c.d.e), which is not ideal.
To Reproduce
Steps to reproduce the behavior:
The following tree of nested attributes:
.. py:attribute:: a
a
.. py:attribute:: a.b
b
.. py:attribute:: a.b.c
c
.. py:attribute:: a.b.c.d
d
.. py:attribute:: a.b.c.d.e
e
.. py:attribute:: a.b.c.d.e.f
f
.. py:attribute:: a.b.c.d.e.f.g
g
.. py:attribute:: a.b.c.d.e.f.h
h
gets converted to the HTML shown under the "Screenshots" section below. Note that the first attribute at every odd depth has its name stripped. Note also that the second attribute at the final depth (a.b.c.d.e.f.h) does not get stripped since it's not the first attribute at that depth.
A workaround is to duplicate the part that would be stripped on every name, like so:
.. py:attribute:: a
a
.. py:attribute:: a.b
b
.. py:attribute:: a.a.b.c
c
.. py:attribute:: a.b.a.b.c.d
d
.. py:attribute:: a.b.c.a.b.c.d.e
e
.. py:attribute:: a.b.c.d.a.b.c.d.e.f
f
.. py:attribute:: a.b.c.d.e.a.b.c.d.e.f.g
g
.. py:attribute:: a.b.c.d.e.f.h
h
Expected behavior
I expect all of the nested attributes to display their full names.
Your project
We plan to use a similar pattern to this in https://docs.graphcore.ai/en/latest/.
Screenshots

Environment info
- OS: Ubuntu 18.04
- Python version: 3.6.9
- Sphinx version: 3.3.1 [via sphinx-build --version]
- Sphinx extensions: - [none relevant to this example IIRC]
- Extra tools: Browser
Additional context
It appears there was a similar problem in #8657, but that one didn't involve just attribute display names. However, if this type of usage isn't supported, is there a place in the Sphinx documentation I can look to that discusses the behaviour when nesting domains more generally?
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 with sphinx/domains/python.py at the linked line around 424 and reproduce the nested py:attribute tree from the report. Trace how nested attribute names and the classname are represented in the underlying node tree, checking whether the behavior affects outputs beyond HTML. Done means every nested attribute displays its full name, including the first attribute at each depth.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100