sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.57k stars 2.12k forks source link

Inheritance diagram doesn't work with packages #5523

Open themightyoarfish opened 6 years ago

themightyoarfish commented 6 years ago

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

KM4YRI commented 6 years ago

See the proposed fix that I wrote over at #5518, I believe it would work.

themightyoarfish commented 6 years ago

I applied your proposed fix, but it doesn't do anything in this case.

themightyoarfish commented 6 years ago

I mean the modified try_import definitely retrieves the class correctly (I don't know if that was the case before, but since my error is a reference one and not an import one I think yes), but the error stays the same, seems to come from a different part of the library.

themightyoarfish commented 6 years ago

Also, if I use .. automodule:: package.subpackage.module instead, the build also runs. I don't understand what the logic is here.