sphinx-doc / sphinx-doc/sphinx
Inheritance diagram doesn't work with packages
Nobody has claimed this yet.
- 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
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 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