Closed mhostetter closed 2 years ago
The build output is below. I'm guessing the warnings are relevant.
$ rm -rf docs/build && rm -rf docs/api && sphinx-build -b dirhtml -v docs/ docs/build/
Running Sphinx v5.0.0
/usr/lib/python3/dist-packages/requests/__init__.py:89: RequestsDependencyWarning: urllib3 (1.26.11) or chardet (3.0.4) doesn't match a supported version!
warnings.warn("urllib3 ({}) or chardet ({}) doesn't match a supported "
making output directory... done
locale_dir /mnt/c/Users/matth/repos/foo-147/docs/locales/en/LC_MESSAGES does not exists
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
loading intersphinx inventory from https://numpy.org/doc/stable/objects.inv...
locale_dir /mnt/c/Users/matth/repos/foo-147/docs/locales/en/LC_MESSAGES does not exists
building [mo]: targets for 0 po files that are out of date
building [dirhtml]: targets for 2 source files that are out of date
updating environment: locale_dir /mnt/c/Users/matth/repos/foo-147/docs/locales/en/LC_MESSAGES does not exists
[new config] 4 added, 0 changed, 0 removed
reading sources... [ 25%] api
reading sources... [ 50%] api/foo.B
reading sources... [ 75%] api/foo.B.something
reading sources... [100%] index
/mnt/c/Users/matth/repos/foo-147/docs/api.rst.rst:12: WARNING: No top-level Python API group named: 'public-members', valid groups are: ['classes']
/mnt/c/Users/matth/repos/foo-147/docs/foo.B.something.rst:1: WARNING: object-id 'foo.B.something' for 'B.something' does not start with module name 'foo._bar.'
/mnt/c/Users/matth/repos/foo-147/docs/foo.B.something.rst:1: WARNING: object-id 'foo.B.something' for 'foo.B.something' does not start with module name 'foo._bar.'
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... WARNING: unsupported theme option 'social' given
done
writing output... [ 25%] api
writing output... [ 50%] api/foo.B
writing output... [ 75%] api/foo.B.something
writing output... [100%] index
foo.B.something:1: WARNING: py:obj reference target not found: foo.B.something
generating indices... genindex done
writing additional pages... done
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
Generating sitemap for 5 pages in /mnt/c/Users/matth/repos/foo-147/docs/build/sitemap.xml
build succeeded, 5 warnings.
The HTML pages are in docs/build.
I have another example that may elucidate the phenomena that's happening. I discovered that this "foo._bar.foo.B.something
not foo.B.something
" phenomenon is import order dependent.
Here's a new example. foo-147-v2.zip
# foo/__init__.py
from ._bravo import Bravo
from ._charlie import Charlie
# foo/__init__.py
from ._alpha import Alpha
from ._bravo import Bravo
Notice the methods inherited from Bravo
are white and not linked.
A page does exist but it has the wrong name -- the same issue as in the original example.
Since from ._alpha import Alpha
is done first and inside _alpha.py
Bravo
is imported, it seems that Bravo
definition conflicts with the Bravo
that is imported later in __init__.py
.
fixed in v0.9.0
I noticed that documenting undocumented parent methods has an issue with the object name and cross-linking. Here is a self-contained reproducer foo-147.zip.
AbstractBase
is not documented / is not a public class in thefoo
package.Notice
something
is white and unlinked.Notice the URL is correct as
api/foo.B.something/
, however the object name isfoo._bar.foo.B.something
notfoo.B.something
.