1.0.4: sphinx warnings `reference target not found`

[kloczek]

First 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 v5.0.1
making output directory... done
WARNING: html_static_path entry '_static' does not exist
building [mo]: targets for 0 po files that are out of date
building [man]: all manpages
updating environment: [new config] 3 added, 0 changed, 0 removed
reading sources... [100%] index
WARNING: autodoc: failed to import function 'pack' from module 'msgpack'; the following exception was raised:
No module named 'msgpack'
WARNING: autodoc: failed to import function 'packb' from module 'msgpack'; the following exception was raised:
No module named 'msgpack'
WARNING: autodoc: failed to import function 'unpack' from module 'msgpack'; the following exception was raised:
No module named 'msgpack'
WARNING: autodoc: failed to import function 'unpackb' from module 'msgpack'; the following exception was raised:
No module named 'msgpack'
WARNING: autodoc: failed to import class 'Packer' from module 'msgpack'; the following exception was raised:
No module named 'msgpack'
WARNING: autodoc: failed to import class 'Unpacker' from module 'msgpack'; the following exception was raised:
No module named 'msgpack'
WARNING: autodoc: failed to import class 'ExtType' from module 'msgpack'; the following exception was raised:
No module named 'msgpack'
WARNING: autodoc: failed to import class 'Timestamp' from module 'msgpack'; the following exception was raised:
No module named 'msgpack'
WARNING: autodoc: failed to import module 'exceptions' from module 'msgpack'; the following exception was raised:
No module named 'msgpack'
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-msgpack.3 { api advanced } /home/tkloczko/rpmbuild/BUILD/msgpack-python-1.0.4/docs/api.rst:8: WARNING: py:func reference target not found: dump
/home/tkloczko/rpmbuild/BUILD/msgpack-python-1.0.4/docs/api.rst:8: WARNING: py:func reference target not found: pack
/home/tkloczko/rpmbuild/BUILD/msgpack-python-1.0.4/docs/api.rst:12: WARNING: py:func reference target not found: dumps
/home/tkloczko/rpmbuild/BUILD/msgpack-python-1.0.4/docs/api.rst:12: WARNING: py:func reference target not found: packb
/home/tkloczko/rpmbuild/BUILD/msgpack-python-1.0.4/docs/api.rst:16: WARNING: py:func reference target not found: load
/home/tkloczko/rpmbuild/BUILD/msgpack-python-1.0.4/docs/api.rst:16: WARNING: py:func reference target not found: unpack
/home/tkloczko/rpmbuild/BUILD/msgpack-python-1.0.4/docs/api.rst:20: WARNING: py:func reference target not found: loads
/home/tkloczko/rpmbuild/BUILD/msgpack-python-1.0.4/docs/api.rst:20: WARNING: py:func reference target not found: unpackb
/home/tkloczko/rpmbuild/BUILD/msgpack-python-1.0.4/docs/advanced.rst:10: WARNING: py:class reference target not found: msgpack.Packer
/home/tkloczko/rpmbuild/BUILD/msgpack-python-1.0.4/docs/advanced.rst:13: WARNING: py:meth reference target not found: msgpack.Packer.bytes
/home/tkloczko/rpmbuild/BUILD/msgpack-python-1.0.4/docs/advanced.rst:13: WARNING: py:meth reference target not found: msgpack.Packer.getbuffer
done
build succeeded, 21 warnings.

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

--- a/docs/conf.py~     2022-06-05 08:01:50.000000000 +0000
+++ b/docs/conf.py      2022-06-05 08:02:43.878255796 +0000
@@ -16,7 +16,7 @@
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-# sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath(".."))

 # -- General configuration -----------------------------------------------------
 author = "Inada Naoki"

This patch fixes what is in the comment and that can of fix 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.

+ /usr/bin/sphinx-build -n -T -b man docs build/sphinx/man
Running Sphinx v5.0.1
making output directory... done
WARNING: html_static_path entry '_static' does not exist
building [mo]: targets for 0 po files that are out of date
building [man]: all manpages
updating environment: [new config] 3 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-msgpack.3 { api advanced } /home/tkloczko/rpmbuild/BUILD/msgpack-python-1.0.4/docs/api.rst:8: WARNING: py:func reference target not found: dump
/home/tkloczko/rpmbuild/BUILD/msgpack-python-1.0.4/docs/api.rst:12: WARNING: py:func reference target not found: dumps
/home/tkloczko/rpmbuild/BUILD/msgpack-python-1.0.4/docs/api.rst:16: WARNING: py:func reference target not found: load
/home/tkloczko/rpmbuild/BUILD/msgpack-python-1.0.4/docs/api.rst:20: WARNING: py:func reference target not found: loads
/home/tkloczko/rpmbuild/BUILD/msgpack-python-1.0.4/msgpack/fallback.py:docstring of msgpack.fallback.Packer:: WARNING: py:class reference target not found: callable
/home/tkloczko/rpmbuild/BUILD/msgpack-python-1.0.4/msgpack/fallback.py:docstring of msgpack.fallback.Unpacker:6: WARNING: py:meth reference target not found: feed
/home/tkloczko/rpmbuild/BUILD/msgpack-python-1.0.4/msgpack/fallback.py:docstring of msgpack.fallback.Unpacker:: WARNING: py:class reference target not found: callable
/home/tkloczko/rpmbuild/BUILD/msgpack-python-1.0.4/msgpack/fallback.py:docstring of msgpack.fallback.Unpacker:: WARNING: py:class reference target not found: callable
/home/tkloczko/rpmbuild/BUILD/msgpack-python-1.0.4/msgpack/ext.py:docstring of msgpack.ext.Timestamp.from_unix:: WARNING: py:class reference target not found: float.
/home/tkloczko/rpmbuild/BUILD/msgpack-python-1.0.4/msgpack/ext.py:docstring of msgpack.ext.Timestamp.to_datetime:: WARNING: py:class reference target not found: datetime.
done
build succeeded, 11 warnings.

You can peak on fixes that kind of issues in other projects https://github.com/latchset/jwcrypto/pull/289 https://github.com/click-contrib/sphinx-click/commit/abc31069 https://github.com/latchset/jwcrypto/pull/289 https://github.com/RDFLib/rdflib-sqlalchemy/issues/95 https://github.com/sissaschool/elementpath/commit/bf869d9e