5.1.0: sphinx warnings `reference target not found`

[kloczek]

Fiirs of all currently it is not possible to use straight sphinx-build command to build documentation out of source tree

+ /usr/bin/sphinx-build -n -T -b man docs build/sphinx/man
Running Sphinx v4.5.0
making output directory... done
building [mo]: targets for 0 po files that are out of date
building [man]: all manpages
updating environment: [new config] 1 added, 0 changed, 0 removed
reading sources... [100%] index
WARNING: autodoc: failed to import class 'Cache' from module 'cachetools'; the following exception was raised:
No module named 'cachetools'
WARNING: autodoc: failed to import class 'FIFOCache' from module 'cachetools'; the following exception was raised:
No module named 'cachetools'
WARNING: autodoc: failed to import class 'LFUCache' from module 'cachetools'; the following exception was raised:
No module named 'cachetools'
WARNING: autodoc: failed to import class 'LRUCache' from module 'cachetools'; the following exception was raised:
No module named 'cachetools'
WARNING: autodoc: failed to import class 'MRUCache' from module 'cachetools'; the following exception was raised:
No module named 'cachetools'
WARNING: autodoc: failed to import class 'RRCache' from module 'cachetools'; the following exception was raised:
No module named 'cachetools'
WARNING: autodoc: failed to import class 'TTLCache' from module 'cachetools'; the following exception was raised:
No module named 'cachetools'
WARNING: autodoc: failed to import class 'TLRUCache' from module 'cachetools'; the following exception was raised:
No module named 'cachetools'
WARNING: autodoc: failed to import function 'keys.hashkey' from module 'cachetools'; the following exception was raised:
No module named 'cachetools'
WARNING: autodoc: failed to import function 'keys.typedkey' from module 'cachetools'; the following exception was raised:
No module named 'cachetools'
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-cachetools.3 { } /home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:32: WARNING: py:class reference target not found: Cache
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:32: WARNING: py:class reference target not found: collections.MutableMapping
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:32: WARNING: py:attr reference target not found: maxsize
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:32: WARNING: py:attr reference target not found: currsize
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:32: WARNING: py:meth reference target not found: Cache.__setitem__
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:32: WARNING: py:meth reference target not found: self.popitem
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:41: WARNING: py:class reference target not found: Cache
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:41: WARNING: py:meth reference target not found: getsizeof
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:41: WARNING: py:meth reference target not found: getsizeof
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:41: WARNING: py:const reference target not found: 1
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:50: WARNING: py:class reference target not found: Cache
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:193: WARNING: py:meth reference target not found: popitem
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:213: WARNING: py:class reference target not found: collections.defaultdict
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:213: WARNING: py:class reference target not found: Cache
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:213: WARNING: py:meth reference target not found: __missing__
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:213: WARNING: py:meth reference target not found: Cache.__getitem__
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:264: WARNING: py:class reference target not found: weakref.WeakValueDictionary
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:271: WARNING: py:func reference target not found: cachetools.keys.hashkey
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:277: WARNING: py:const reference target not found: None
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:277: WARNING: py:class reference target not found: threading.Lock
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:289: WARNING: py:attr reference target not found: cache
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:289: WARNING: py:attr reference target not found: cache_key
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:289: WARNING: py:attr reference target not found: cache_lock
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:315: WARNING: py:attr reference target not found: __wrapped__
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:356: WARNING: py:const reference target not found: self
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:356: WARNING: py:const reference target not found: cls
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:440: WARNING: py:func reference target not found: cached
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:440: WARNING: py:func reference target not found: cachedmethod
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:473: WARNING: py:func reference target not found: envkey
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:484: WARNING: py:func reference target not found: functools.lru_cache
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:489: WARNING: py:func reference target not found: functools.lru_cache
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:489: WARNING: py:const reference target not found: None
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:497: WARNING: py:const reference target not found: True
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:511: WARNING: py:func reference target not found: cache_parameters
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:516: WARNING: py:func reference target not found: cache_info
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:516: WARNING: py:func reference target not found: cache_clear
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:516: WARNING: py:func reference target not found: functools.lru_cache
done
build succeeded, 47 warnings.

First batch of warnings can be fixed by patch like below:

--- a/docs/conf.py~     2022-05-15 20:37:38.000000000 +0000
+++ b/docs/conf.py      2022-05-17 17:28:17.016511154 +0000
@@ -1,3 +1,8 @@
+import os
+import sys
+
+sys.path.append(os.path.abspath('../src'))
+
 def get_version():
     import configparser
     import pathlib

This patch is suggested in sphinx example copy py https://www.sphinx-doc.org/en/master/usage/configuration.html#example-of-configuration-file

Than .. on building my packages I'm using sphinx-build command with -n switch which shows warmings about missing references. These are not critical issues.

On building my packages I'm using sphinx-build command with -n switch which shows warmings about missing references. These are not critical issues.
Here is the output with warnings:

+ /usr/bin/sphinx-build -n -T -b man docs build/sphinx/man
Running Sphinx v4.5.0
making output directory... done
building [mo]: targets for 0 po files that are out of date
building [man]: all manpages
updating environment: [new config] 1 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-cachetools.3 { } /home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:32: WARNING: py:class reference target not found: collections.MutableMapping
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:32: WARNING: py:attr reference target not found: maxsize
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:32: WARNING: py:attr reference target not found: currsize
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:32: WARNING: py:meth reference target not found: Cache.__setitem__
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:32: WARNING: py:meth reference target not found: self.popitem
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:41: WARNING: py:meth reference target not found: getsizeof
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:41: WARNING: py:meth reference target not found: getsizeof
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:41: WARNING: py:const reference target not found: 1
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:67: WARNING: py:meth reference target not found: popitem
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:67: WARNING: py:meth reference target not found: popitem
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:67: WARNING: py:meth reference target not found: __getitem__
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:67: WARNING: py:meth reference target not found: __setitem__
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:67: WARNING: py:meth reference target not found: __delitem__
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:104: WARNING: py:func reference target not found: random.choice
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:118: WARNING: py:func reference target not found: time.monotonic
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:140: WARNING: py:meth reference target not found: __setitem__
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:140: WARNING: py:meth reference target not found: __delitem__
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:140: WARNING: py:const reference target not found: None
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:180: WARNING: py:meth reference target not found: __setitem__
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:180: WARNING: py:meth reference target not found: __delitem__
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:180: WARNING: py:const reference target not found: None
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:193: WARNING: py:meth reference target not found: popitem
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:213: WARNING: py:class reference target not found: collections.defaultdict
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:213: WARNING: py:meth reference target not found: __missing__
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:213: WARNING: py:meth reference target not found: Cache.__getitem__
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:264: WARNING: py:class reference target not found: weakref.WeakValueDictionary
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:277: WARNING: py:const reference target not found: None
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:277: WARNING: py:class reference target not found: threading.Lock
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:289: WARNING: py:attr reference target not found: cache
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:289: WARNING: py:attr reference target not found: cache_key
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:289: WARNING: py:attr reference target not found: cache_lock
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:315: WARNING: py:attr reference target not found: __wrapped__
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:356: WARNING: py:const reference target not found: self
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:356: WARNING: py:const reference target not found: cls
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:440: WARNING: py:func reference target not found: cached
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:440: WARNING: py:func reference target not found: cachedmethod
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:473: WARNING: py:func reference target not found: envkey
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:484: WARNING: py:func reference target not found: functools.lru_cache
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:489: WARNING: py:func reference target not found: functools.lru_cache
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:489: WARNING: py:const reference target not found: None
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:497: WARNING: py:const reference target not found: True
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:511: WARNING: py:func reference target not found: cache_parameters
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:516: WARNING: py:func reference target not found: cache_info
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:516: WARNING: py:func reference target not found: cache_clear
/home/tkloczko/rpmbuild/BUILD/cachetools-5.1.0/docs/index.rst:516: WARNING: py:func reference target not found: functools.lru_cache
done
build succeeded, 45 warnings.

You can peak on fixes that kind of issues in other projects
latchset/jwcrypto#289
click-contrib/sphinx-click@abc31069

[tkem]

@kloczek: Thanks for reporting!

Regarding the first batch of warnings, this seems to be an issue if the package hasn't been installed before running sphinx, e.g. pip3 install --prefix=~/.local -e .. Both tox and RTD apparently install the package beforehand, so this hasn't shown up before. But I agree, this should be fixed by adding the src dir to sys.path, as you suggested.

Regarding the second batch, I never found sphinx's -n (nitpicking) mode that useful. Something like :const:`1` resulting in

WARNING: py:const reference target not found: 1

isn't something I want to deal with, frankly. So I'd prefer to leave it as-is, and kindly ask you to ignore the warnings...

[kloczek]

Regarding the first batch of warnings, this seems to be an issue if the package hasn't been installed before running sphinx, e.g. pip3 install --prefix=~/.local -e .

That is is something really odd that python modules to generate documentations somehow needs to be installed.
If you will look outsode python domain literally NONE of the projects have such requirements.
That few lines patch brings everythiog to the state where ALLWAYS generate documentsation will mean "generate it out of source tree".
As I wtote that small sys.path is even suggested by sphinx doicumentation.
If you don;t like it that is no my proble, In my buikd porocedure I don't need to waste time on installiation .. KISS principle.

[tkem]

That is is something really odd that python modules to generate documentations somehow needs to be installed.

I didn't say that it needs to be installed. I just said that the toolchain I use apparently just does that, so I never saw that warnings. Anyway, it should be fixed in the next release.

[kloczek]

Tested new 5.2.0 and looks like main issue with broken refs still is not resolved .. 🤔

[tkem]

As I stated before,

I never found sphinx's -n (nitpicking) mode that useful.
[...]
So I'd prefer to leave it as-is, and kindly ask you to ignore the warnings...

I still don't see much benefit in adapting the docs to silence sphinx's nitpicking mode, so this will not be changed.

However, it should now be possible to build the sphinx docs without installing the package beforehand.

[kloczek]

Look .. that issue is not affecting me at all because I'm only interested roff output (man page).
This issue is affecting mostly html output and probably few other which sphinx can generate.
If you don't care about not have active links for example API routines names pointing to the description that is not my problem.
I'm just/only a messenger.
I've opened that ticket because I'm trying to give as much as possible from results of my work to the maintainers.

I can drop you tree more fixes similar issue.
latchset/jwcrypto#289
RDFLib/rdflib-sqlalchemy#95
sissaschool/elementpath@bf869d9e

[kloczek]

Not fixing those warnings mostly affects html output. One of the examples is part of the text with API routine name only higlited and withoyt link to actual description.

[tkem]

To get this straight: I do appreciate your input, pointing me to some issues I missed so far. Building sphinx docs without having to install the package beforehand I did fix in the latest release, AFAICS.
However, HTML output is already "good enough" in my opinion - inter-project links work as they should, and I don't think it's worth the effort to silence those "nitpicking" warnings. But if I see any problems with that in the future, at least I know where I have to look now, so thanks!

[kloczek]

Those warnings are affecting mostly html output.
Good example of that kid of issue is missing link in text where is for example highlighted routine name.
As I'm not interested html and only roff output (man page) I'm not affected by that issue 😋
If you need more examples of fixing those issues I can provide more links as some maintainers managed to sort out those issues switching own CIs to show "nitpicking" warnings😃