24.1.0: 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:

+ /usr/bin/sphinx-build -n -T -b man doc build/sphinx/man
Running Sphinx v7.2.6
making output directory... done
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
loading intersphinx inventory from https://cryptography.io/en/latest/objects.inv...
building [mo]: targets for 0 po files that are out of date
writing output...
building [man]: all manpages
updating environment: [new config] 9 added, 0 changed, 0 removed
reading sources... [100%] introduction
WARNING: autodoc: failed to import function 'crypto.get_elliptic_curves' from module 'OpenSSL'; the following exception was raised:
No module named 'OpenSSL'
WARNING: autodoc: failed to import function 'crypto.get_elliptic_curve' from module 'OpenSSL'; the following exception was raised:
No module named 'OpenSSL'
WARNING: autodoc: failed to import function 'crypto.dump_certificate' from module 'OpenSSL'; the following exception was raised:
No module named 'OpenSSL'
WARNING: autodoc: failed to import function 'crypto.load_certificate' from module 'OpenSSL'; the following exception was raised:
No module named 'OpenSSL'
WARNING: autodoc: failed to import function 'crypto.dump_certificate_request' from module 'OpenSSL'; the following exception was raised:
No module named 'OpenSSL'
WARNING: autodoc: failed to import function 'crypto.load_certificate_request' from module 'OpenSSL'; the following exception was raised:
No module named 'OpenSSL'
WARNING: autodoc: failed to import function 'crypto.dump_privatekey' from module 'OpenSSL'; the following exception was raised:
No module named 'OpenSSL'
WARNING: autodoc: failed to import function 'crypto.load_privatekey' from module 'OpenSSL'; the following exception was raised:
No module named 'OpenSSL'
WARNING: autodoc: failed to import function 'crypto.dump_publickey' from module 'OpenSSL'; the following exception was raised:
No module named 'OpenSSL'
WARNING: autodoc: failed to import function 'crypto.load_publickey' from module 'OpenSSL'; the following exception was raised:
No module named 'OpenSSL'
WARNING: autodoc: failed to import function 'crypto.dump_crl' from module 'OpenSSL'; the following exception was raised:
No module named 'OpenSSL'
WARNING: autodoc: failed to import function 'crypto.load_crl' from module 'OpenSSL'; the following exception was raised:
No module named 'OpenSSL'
WARNING: autodoc: failed to import function 'crypto.sign' from module 'OpenSSL'; the following exception was raised:
No module named 'OpenSSL'
WARNING: autodoc: failed to import function 'crypto.verify' from module 'OpenSSL'; the following exception was raised:
No module named 'OpenSSL'
WARNING: autodoc: failed to import class 'crypto.X509' from module 'OpenSSL'; the following exception was raised:
No module named 'OpenSSL'
WARNING: autodoc: failed to import class 'crypto.X509Name' from module 'OpenSSL'; the following exception was raised:
No module named 'OpenSSL'
WARNING: autodoc: failed to import class 'crypto.X509Req' from module 'OpenSSL'; the following exception was raised:
No module named 'OpenSSL'
WARNING: autodoc: failed to import class 'crypto.X509Store' from module 'OpenSSL'; the following exception was raised:
No module named 'OpenSSL'
WARNING: autodoc: failed to import class 'crypto.X509StoreContextError' from module 'OpenSSL'; the following exception was raised:
No module named 'OpenSSL'
WARNING: autodoc: failed to import class 'crypto.X509StoreContext' from module 'OpenSSL'; the following exception was raised:
No module named 'OpenSSL'
WARNING: autodoc: failed to import class 'crypto.X509StoreFlags' from module 'OpenSSL'; the following exception was raised:
No module named 'OpenSSL'
WARNING: autodoc: failed to import class 'crypto.PKey' from module 'OpenSSL'; the following exception was raised:
No module named 'OpenSSL'
WARNING: autodoc: failed to import class 'crypto.X509Extension' from module 'OpenSSL'; the following exception was raised:
No module named 'OpenSSL'
WARNING: autodoc: failed to import class 'crypto.CRL' from module 'OpenSSL'; the following exception was raised:
No module named 'OpenSSL'
WARNING: autodoc: failed to import class 'crypto.Revoked' from module 'OpenSSL'; the following exception was raised:
No module named 'OpenSSL'
WARNING: autodoc: failed to import function 'SSL.OpenSSL_version' from module 'OpenSSL'; the following exception was raised:
No module named 'OpenSSL'
WARNING: autodoc: failed to import class 'SSL.Context' from module 'OpenSSL'; the following exception was raised:
No module named 'OpenSSL'
WARNING: autodoc: failed to import class 'SSL.Session' from module 'OpenSSL'; the following exception was raised:
No module named 'OpenSSL'
WARNING: autodoc: failed to import class 'SSL.Context' from module 'OpenSSL'; the following exception was raised:
No module named 'OpenSSL'
WARNING: autodoc: failed to import class 'SSL.Connection' from module 'OpenSSL'; the following exception was raised:
No module named 'OpenSSL'
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-pyopenssl.3 { introduction install api api/crypto api/ssl internals backward-compatibility changelog } /home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/api/crypto.rst:3: WARNING: py:mod reference target not found: crypto
/home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/api/crypto.rst:202: WARNING: py:const reference target not found: b"sha256"
/home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/api/crypto.rst:202: WARNING: py:const reference target not found: b"sha384"
/home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/api/ssl.rst:3: WARNING: py:mod reference target not found: SSL
/home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/api/ssl.rst:23: WARNING: py:class reference target not found: Context
/home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/api/ssl.rst:23: WARNING: py:const reference target not found: *_METHOD
/home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/api/ssl.rst:43: WARNING: py:meth reference target not found: set_verify
/home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/api/ssl.rst:50: WARNING: py:meth reference target not found: use_certificate_file
/home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/api/ssl.rst:50: WARNING: py:meth reference target not found: use_privatekey_file
/home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/api/ssl.rst:57: WARNING: py:meth reference target not found: set_options
/home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/api/ssl.rst:65: WARNING: py:meth reference target not found: set_options
/home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/api/ssl.rst:73: WARNING: py:meth reference target not found: set_options
/home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/api/ssl.rst:80: WARNING: py:meth reference target not found: set_options
/home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/api/ssl.rst:92: WARNING: py:meth reference target not found: set_options
/home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/api/ssl.rst:94: WARNING: py:const reference target not found: OP_NO_*
/home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/api/ssl.rst:113: WARNING: py:meth reference target not found: OpenSSL_version
/home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/api/ssl.rst:113: WARNING: py:func reference target not found: OpenSSL_version
/home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/api/ssl.rst:127: WARNING: py:meth reference target not found: Context.set_session_cache_mode
/home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/api/ssl.rst:127: WARNING: py:func reference target not found: SSL_CTX_set_session_cache_mode
/home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/api/ssl.rst:136: WARNING: py:func reference target not found: SSLeay_version
/home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/api/ssl.rst:143: WARNING: py:meth reference target not found: Context.set_alpn_select_callback
/home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/api/ssl.rst:155: WARNING: py:class reference target not found: Context
/home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/api/ssl.rst:166: WARNING: py:class reference target not found: Connection
/home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/api/ssl.rst:174: WARNING: py:class reference target not found: Context
/home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/api/ssl.rst:174: WARNING: py:meth reference target not found: bio_read
/home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/api/ssl.rst:174: WARNING: py:meth reference target not found: bio_write
/home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/api/ssl.rst:174: WARNING: py:meth reference target not found: bio_shutdown
/home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/api/ssl.rst:193: WARNING: py:data reference target not found: SSL_ERROR_ZERO_RETURN
/home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/api/ssl.rst:200: WARNING: py:data reference target not found: SSL_ERROR
/home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/api/ssl.rst:210: WARNING: py:meth reference target not found: OpenSSL.SSL.Connection.recv
/home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/api/ssl.rst:210: WARNING: py:meth reference target not found: OpenSSL.SSL.Connection.send
/home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/api/ssl.rst:210: WARNING: py:meth reference target not found: OpenSSL.SSL.Connection.do_handshake
/home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/api/ssl.rst:210: WARNING: py:meth reference target not found: select
/home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/internals.rst:40: WARNING: py:class reference target not found: SSL.Connection
/home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/internals.rst:52: WARNING: py:class reference target not found: socket
/home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/internals.rst:52: WARNING: py:class reference target not found: SSL.Connection
/home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/internals.rst:52: WARNING: py:meth reference target not found: fileno
/home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/internals.rst:52: WARNING: py:meth reference target not found: connect
/home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/internals.rst:52: WARNING: py:meth reference target not found: accept
/home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/internals.rst:52: WARNING: py:class reference target not found: SSL.Connection
/home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/internals.rst:52: WARNING: py:class reference target not found: SSL.Connection
/home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/internals.rst:61: WARNING: py:meth reference target not found: fileno
/home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/internals.rst:61: WARNING: py:meth reference target not found: read
/home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/internals.rst:61: WARNING: py:meth reference target not found: write
/home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/internals.rst:61: WARNING: py:meth reference target not found: fileno
/home/tkloczko/rpmbuild/BUILD/pyopenssl-24.1.0/doc/internals.rst:61: WARNING: py:class reference target not found: SSL.Connection
done
build succeeded, 76 warnings.

You can peak on fixes that kind of issues in other projects https://github.com/RDFLib/rdflib-sqlalchemy/issues/95 https://github.com/RDFLib/rdflib/pull/2036 https://github.com/click-contrib/sphinx-click/commit/abc31069 https://github.com/frostming/unearth/issues/14 https://github.com/jaraco/cssutils/issues/21 https://github.com/latchset/jwcrypto/pull/289 https://github.com/latchset/jwcrypto/pull/289 https://github.com/pypa/distlib/commit/98b9b89f https://github.com/pywbem/pywbem/pull/2895 https://github.com/sissaschool/elementpath/commit/bf869d9e https://github.com/sissaschool/xmlschema/commit/42ea98f2 https://github.com/sqlalchemy/sqlalchemy/commit/5e88e6e8

[kloczek]

BTW firs part of the warnings is possible to fix using below patch

--- a/doc/conf.py
+++ b/doc/conf.py
@@ -16,6 +16,7 @@
 import sys

 HERE = os.path.abspath(os.path.dirname(__file__))
+sys.path.insert(0, os.path.abspath("../src"))


 def read_file(*parts):

Please let me know if you want that as PR.