sphinx-doc / sphinx-doc/sphinx

Inheritance diagram doesn't work with packages

Open
#5,523 4 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

Problem

The inability of Sphinx to work with (sub)packages comes up occasionally (see e.g. https://stackoverflow.com/questions/51881692/how-can-i-use-sphinx-with-subpackages-without-duplicating-everything), but I have met this issue again when using the inheritance-diagrams extension.

I have this package structure

package/
├── __init__.py
└── subpackage
    ├── __init__.py
    └── module.py

The files are given here:

package/init.py

from . import subpackage

package.subpackage/init.py

from .module import Class
__all__ = ['Class']

package.subpackage/module.py

class Class(object):
    pass

So in summary, I'm using subpackages so I can write package.subpackage.Class instead of package.subpackage.module.Class.

My sphinx configuration looks like this:
Makefile

SPHINXOPTS    = -W -n
SPHINXBUILD   = sphinx-build
SPHINXPROJ    = test
SOURCEDIR     = source
BUILDDIR      = build

# Put it first so that "make" without argument is like "make help".
help:
        @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

.PHONY: help Makefile

%: Makefile
        @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

conf.py

import os
import sys
sys.path.insert(0, os.path.abspath('.'))
sys.path.insert(0, os.path.abspath('../../'))
import sphinx_bootstrap_theme

project = 'test'
copyright = ''
author = ''

version = ''
release = '0'

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.intersphinx',
    'sphinx.ext.mathjax',
    'sphinx.ext.githubpages',
    'sphinx.ext.napoleon',
    'sphinxarg.ext',
    'sphinx.ext.viewcode',
    'sphinx.ext.inheritance_diagram',
]

source_suffix = '.rst'
master_doc = 'index'
language = None
exclude_patterns = []

pygments_style = 'sphinx'
highlight_language = 'python3'

html_theme = 'bootstrap'
html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()

html_theme_options = {
    'navbar_class': 'navbar navbar-inverse',
    'bootswatch_theme': 'flatly'
}

htmlhelp_basename = 'testdoc'



# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {
    'python':       ('https://docs.python.org/', None),
}

autodoc_member_order = 'bysource'

index.rst

Package
=======

API reference
-------------

.. toctree::
   :maxdepth: 5

   package.subpackage

package.subpackage.rst

.. contents::

package.subpackage
==================

Module Contents
---------------

.. automodule:: package.subpackage
    :members:
    :undoc-members:
    :show-inheritance:

.. inheritance-diagram:: Class
Error logs / results
Warning, treated as error:
test/sphinx/source/package.subpackage.rst:14:py:class reference target not found: package.subpackage.module.Class
Expected results

Sphinx can either resolve a reference such as package.subpackage.module.Class or ideally package.subpackage.Class. Neither works.

Reproducible project / your project

All files are attached:
Archive.zip

Environment info
  • OS: Ubuntu 16.04
  • Python version: 3.6.5
  • Sphinx version: 1.7.5

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 the reproduced package structure and package.subpackage.rst, then inspect the sphinx.ext.inheritance_diagram extension and run the attached project with the documented Sphinx configuration. Trace how the diagram resolves Class references for re-exported package classes. Done means the inheritance diagram resolves package.subpackage.module.Class or package.subpackage.Class without the reported warning.

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
Clearly specified
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.