sphinx-doc / sphinx-doc/sphinx

Some nested attribute names are stripped

Open
#9,099 5 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

domains:py type:bug
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
Screenshot 2021-04-14 at 13 45 27

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

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 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.