sphinx-doc / sphinx-doc/sphinx

Broken graph when `sphinx.ext.inheritance_diagram` `:parts:` directive removes distinguishing path components

Open
#11,287 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

extensions:graphviz
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

Describe the bug

When generating an inheritance diagram using sphinx.ext.inheritance_diagram with a :parts: directive that removes distinguishing components from the path (e.g. with :parts: 2 for the inheritance diagram of class a.b.c.d with base class b.c.d), an inheritance graph is generated consisting of a single node with an edge looping back to itself.

This appears to occur because the base name in the class information constructed by InheritanceGraph._class_info is the partial name that depends on the :parts: directive (as generated by InheritanceGraph.class_name, which, contrary to the claim in its docstring, does not return the fully-qualified name), so there is no ability to disambiguate between multiple classes sharing the same partial name when specifying edges in the graph.

How to Reproduce

Relevant conf.py is rather complex, and the considerable effort that would be required to construct a minimal example does not seem to be necessary since the cause of the bug can be determined by inspection of the implementation of sphinx.ext.inheritance_diagram.InheritanceGraph.

Environment Information
Platform:              linux; (Linux-5.19.0-35-generic-x86_64-with-glibc2.35)
Python version:        3.9.15 | packaged by conda-forge | (main, Nov 22 2022, 15:55:03) 
[GCC 10.4.0])
Python implementation: CPython
Sphinx version:        6.1.3
Docutils version:      0.19
Jinja2 version:        3.1.2
Pygments version:      2.14.0
Sphinx extensions
sphinx.ext.inheritance_diagram
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 by reading sphinx.ext.inheritance_diagram.InheritanceGraph, especially _class_info and class_name, and trace how the :parts: value affects class names and graph edges. Reproduce the a.b.c.d and b.c.d case with :parts: 2 if possible, then verify that the diagram retains distinct nodes and does not create a self-loop.

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
Stale
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.