3.0.1: sphinx warnings `reference target not found`

[kloczek]

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:

Details

+ /usr/bin/sphinx-build -n -T -b man docs build/sphinx/man
Running Sphinx v5.0.1
making output directory... done
loading intersphinx inventory from https://docs.python.org/objects.inv...
loading intersphinx inventory from http://www.zodb.org/en/latest/objects.inv...
intersphinx inventory has moved: https://docs.python.org/objects.inv -> https://docs.python.org/3/objects.inv
intersphinx inventory has moved: http://www.zodb.org/en/latest/objects.inv -> https://zodb.org/en/latest/objects.inv
building [mo]: targets for 0 po files that are out of date
building [man]: all manpages
updating environment: [new config] 11 added, 0 changed, 0 removed
reading sources... [100%] sqlalchemy
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-transaction.3 { changes convenience doom savepoint hooks datamanager integrations sqlalchemy api developer } /home/tkloczko/rpmbuild/BUILD/transaction-3.0.1/docs/hooks.rst:8: WARNING: unknown document: resourcemanager
/home/tkloczko/rpmbuild/BUILD/transaction-3.0.1/docs/hooks.rst:18: WARNING: py:meth reference target not found: addBeforeCommitHook
/home/tkloczko/rpmbuild/BUILD/transaction-3.0.1/docs/hooks.rst:184: WARNING: py:meth reference target not found: addAfterCommitHook
/home/tkloczko/rpmbuild/BUILD/transaction-3.0.1/src/transaction/interfaces.py:docstring of transaction.interfaces.ITransactionManager:5: WARNING: py:obj reference target not found: __enter__
/home/tkloczko/rpmbuild/BUILD/transaction-3.0.1/src/transaction/interfaces.py:docstring of transaction.interfaces.ITransactionManager:5: WARNING: py:obj reference target not found: __exit__
docstring of transaction.interfaces.ITransactionManager.registeredSynchs:1: WARNING: py:obj reference target not found: ISynchronizers
docstring of transaction.interfaces.ITransaction.setExtendedInfo:: WARNING: py:class reference target not found: text
docstring of transaction.interfaces.ITransaction.setExtendedInfo:15: WARNING: py:obj reference target not found: <name, value>
docstring of transaction.interfaces.ITransaction.addBeforeCommitHook:: WARNING: py:class reference target not found: sequence
docstring of transaction.interfaces.IDataManager.sortKey:1: WARNING: py:obj reference target not found: IDataManagers
/home/tkloczko/rpmbuild/BUILD/transaction-3.0.1/src/transaction/_manager.py:docstring of transaction._manager.ThreadTransactionManager:1: WARNING: py:class reference target not found: _thread._local
done
build succeeded, 11 warnings.

You can peak on fixes that kind of issues in other projects
latchset/jwcrypto#289
click-contrib/sphinx-click@abc31069
latchset/jwcrypto#289
RDFLib/rdflib-sqlalchemy#95
sissaschool/elementpath@bf869d9e
jaraco/cssutils#21

[kloczek]

Forgot about one detail. To be able use straight sphinx-build command you will need patch like below

--- a/docs/conf.py~     2020-12-11 11:41:37.000000000 +0000
+++ b/docs/conf.py      2022-06-15 15:48:00.760832516 +0000
@@ -12,13 +12,13 @@
 # serve to show the default.

 import sys, os
-import pkg_resources
-
 # 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.append(os.path.abspath('../'))
+sys.path.append(os.path.abspath("../src"))
+
+import pkg_resources
 rqmt = pkg_resources.require('transaction')[0]

 # -- General configuration -----------------------------------------------------

This is workaround on well known pkg_resources issue pypa/setuptools#3279
It meand that it would be good as well migrate from pkg_resources to importlib-metadata 😋