1.3.0: 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 v7.1.2

Traceback (most recent call last):
  File "/usr/lib/python3.8/site-packages/sphinx/config.py", line 356, in eval_config_file
    exec(code, namespace)  # NoQA: S102
  File "/home/tkloczko/rpmbuild/BUILD/authlib-1.3.0/docs/conf.py", line 1, in <module>
    import authlib
ModuleNotFoundError: No module named 'authlib'

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/usr/lib/python3.8/site-packages/sphinx/cmd/build.py", line 285, in build_main
    app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
  File "/usr/lib/python3.8/site-packages/sphinx/application.py", line 207, in __init__
    self.config = Config.read(self.confdir, confoverrides or {}, self.tags)
  File "/usr/lib/python3.8/site-packages/sphinx/config.py", line 179, in read
    namespace = eval_config_file(filename, tags)
  File "/usr/lib/python3.8/site-packages/sphinx/config.py", line 369, in eval_config_file
    raise ConfigError(msg % traceback.format_exc()) from exc
sphinx.errors.ConfigError: There is a programmable error in your configuration file:

Traceback (most recent call last):
  File "/usr/lib/python3.8/site-packages/sphinx/config.py", line 356, in eval_config_file
    exec(code, namespace)  # NoQA: S102
  File "/home/tkloczko/rpmbuild/BUILD/authlib-1.3.0/docs/conf.py", line 1, in <module>
    import authlib
ModuleNotFoundError: No module named 'authlib'


Configuration error:
There is a programmable error in your configuration file:

Traceback (most recent call last):
  File "/usr/lib/python3.8/site-packages/sphinx/config.py", line 356, in eval_config_file
    exec(code, namespace)  # NoQA: S102
  File "/home/tkloczko/rpmbuild/BUILD/authlib-1.3.0/docs/conf.py", line 1, in <module>
    import authlib
ModuleNotFoundError: No module named 'authlib'

This can be fixed by patch like below:

--- a/docs/conf.py
+++ b/docs/conf.py
@@ -1,12 +1,17 @@
-from pallets_sphinx_themes import get_version
+import sys
+import os
+sys.path.insert(0, os.path.abspath("../src"))
+
 from pallets_sphinx_themes import ProjectLink
+import cachelib

 # Project --------------------------------------------------------------

 project = "CacheLib"
 copyright = "2018 Pallets"
 author = "Pallets"
-release, version = get_version("cachelib")
+version = cachelib.__version__
+release = version

 # General --------------------------------------------------------------

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
Please let me know if you want this patch as PR.

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 v7.1.2
making output directory... done
building [mo]: targets for 0 po files that are out of date
writing output...
building [man]: all manpages
updating environment: [new config] 86 added, 0 changed, 0 removed
reading sources... [100%] specs/rfc9068
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-authlib.3 { basic/index basic/intro basic/install basic/logging client/index client/oauth1 client/oauth2 client/requests client/httpx client/frameworks client/flask client/django client/starlette client/fastapi client/api jose/index jose/jws jose/jwe jose/jwk jose/jwt oauth/index oauth/1/index oauth/1/intro oauth/2/index oauth/2/intro oauth/oidc/index oauth/oidc/intro oauth/oidc/core oauth/oidc/discovery flask/index flask/1/index flask/1/authorization-server flask/1/resource-server flask/1/customize flask/1/api flask/2/index flask/2/authorization-server flask/2/grants flask/2/endpoints flask/2/resource-server flask/2/openid-connect flask/2/api django/index django/1/index django/1/authorization-server django/1/resource-server django/1/api django/2/index django/2/authorization-server django/2/grants django/2/endpoints django/2/resource-server django/2/openid-connect django/2/api specs/index specs/rfc5849 specs/rfc6749 specs/rfc6750 specs/rfc7009 specs/rfc7515 specs/rfc7516 specs/rfc7517 specs/rfc7518 specs/rfc7519 specs/rfc7523 specs/rfc7591 specs/rfc7592 specs/rfc7636 specs/rfc7638 specs/rfc7662 specs/rfc8037 specs/rfc8414 specs/rfc8628 specs/rfc9068 specs/oidc community/index community/funding community/support community/security community/contribute community/awesome community/sustainable community/authors community/licenses changelog } /home/tkloczko/rpmbuild/BUILD/authlib-1.3.0/docs/client/httpx.rst:20: WARNING: py:class reference target not found: AssertionClient
/home/tkloczko/rpmbuild/BUILD/authlib-1.3.0/authlib/integrations/requests_client/oauth2_session.py:docstring of authlib.integrations.requests_client.oauth2_session.OAuth2Session:21: WARNING: py:class reference target not found: OAuth2Token
/home/tkloczko/rpmbuild/BUILD/authlib-1.3.0/authlib/integrations/requests_client/oauth2_session.py:docstring of authlib.oauth2.client.OAuth2Client.fetch_token:14: WARNING: py:class reference target not found: OAuth2Token
/home/tkloczko/rpmbuild/BUILD/authlib-1.3.0/authlib/integrations/requests_client/oauth2_session.py:docstring of authlib.oauth2.client.OAuth2Client.refresh_token:9: WARNING: py:class reference target not found: OAuth2Token
/home/tkloczko/rpmbuild/BUILD/authlib-1.3.0/authlib/integrations/httpx_client/oauth1_client.py:docstring of authlib.integrations.httpx_client.oauth1_client.OAuth1Auth.auth_flow:1: WARNING: py:class reference target not found: httpx.Request
/home/tkloczko/rpmbuild/BUILD/authlib-1.3.0/authlib/integrations/httpx_client/oauth1_client.py:docstring of authlib.integrations.httpx_client.oauth1_client.OAuth1Auth.auth_flow:1: WARNING: py:class reference target not found: httpx.Request
/home/tkloczko/rpmbuild/BUILD/authlib-1.3.0/authlib/integrations/httpx_client/oauth1_client.py:docstring of authlib.integrations.httpx_client.oauth1_client.OAuth1Auth.auth_flow:1: WARNING: py:class reference target not found: httpx.Response
/home/tkloczko/rpmbuild/BUILD/authlib-1.3.0/authlib/integrations/httpx_client/oauth2_client.py:docstring of authlib.oauth2.client.OAuth2Client.fetch_token:14: WARNING: py:class reference target not found: OAuth2Token
/home/tkloczko/rpmbuild/BUILD/authlib-1.3.0/authlib/integrations/httpx_client/oauth2_client.py:docstring of authlib.oauth2.client.OAuth2Client.refresh_token:9: WARNING: py:class reference target not found: OAuth2Token
/home/tkloczko/rpmbuild/BUILD/authlib-1.3.0/authlib/integrations/httpx_client/oauth2_client.py:docstring of authlib.oauth2.client.OAuth2Client.fetch_token:14: WARNING: py:class reference target not found: OAuth2Token
/home/tkloczko/rpmbuild/BUILD/authlib-1.3.0/authlib/integrations/httpx_client/oauth2_client.py:docstring of authlib.oauth2.client.OAuth2Client.refresh_token:9: WARNING: py:class reference target not found: OAuth2Token
/home/tkloczko/rpmbuild/BUILD/authlib-1.3.0/authlib/integrations/flask_client/__init__.py:docstring of authlib.integrations.flask_client.OAuth.register:5: WARNING: py:class reference target not found: RemoteApp
/home/tkloczko/rpmbuild/BUILD/authlib-1.3.0/authlib/integrations/django_client/__init__.py:docstring of authlib.integrations.base_client.registry.BaseOAuth.register:5: WARNING: py:class reference target not found: RemoteApp
/home/tkloczko/rpmbuild/BUILD/authlib-1.3.0/authlib/integrations/starlette_client/__init__.py:docstring of authlib.integrations.base_client.registry.BaseOAuth.register:5: WARNING: py:class reference target not found: RemoteApp
/home/tkloczko/rpmbuild/BUILD/authlib-1.3.0/docs/oauth/2/intro.rst:82: WARNING: py:class reference target not found: JWTBearerGrant
/home/tkloczko/rpmbuild/BUILD/authlib-1.3.0/authlib/integrations/flask_oauth1/authorization_server.py:docstring of authlib.integrations.flask_oauth1.authorization_server.AuthorizationServer:1: WARNING: py:class reference target not found: authlib.rfc5849.AuthorizationServer
/home/tkloczko/rpmbuild/BUILD/authlib-1.3.0/docs/flask/2/openid-connect.rst:95: WARNING: py:class reference target not found: OpenIDCode
/home/tkloczko/rpmbuild/BUILD/authlib-1.3.0/docs/flask/2/openid-connect.rst:177: WARNING: py:class reference target not found: OpenIDImplicitGrant
/home/tkloczko/rpmbuild/BUILD/authlib-1.3.0/docs/django/2/openid-connect.rst:103: WARNING: py:class reference target not found: OpenIDCode
/home/tkloczko/rpmbuild/BUILD/authlib-1.3.0/docs/django/2/openid-connect.rst:185: WARNING: py:class reference target not found: OpenIDImplicitGrant
/home/tkloczko/rpmbuild/BUILD/authlib-1.3.0/authlib/oauth2/rfc6749/authorization_server.py:docstring of authlib.oauth2.rfc6749.authorization_server.AuthorizationServer.create_json_request:1: WARNING: py:class reference target not found: authlib.oauth2.rfc6749.requests.JsonRequest
/home/tkloczko/rpmbuild/BUILD/authlib-1.3.0/authlib/oauth2/rfc6749/authorization_server.py:docstring of authlib.oauth2.rfc6749.authorization_server.AuthorizationServer.create_oauth2_request:1: WARNING: py:class reference target not found: authlib.oauth2.rfc6749.requests.OAuth2Request
/home/tkloczko/rpmbuild/BUILD/authlib-1.3.0/authlib/oauth2/rfc6749/resource_protector.py:docstring of authlib.oauth2.rfc6749.resource_protector.ResourceProtector.register_token_validator:1: WARNING: py:class reference target not found: authlib.oauth2.rfc6749.resource_protector.TokenValidator
/home/tkloczko/rpmbuild/BUILD/authlib-1.3.0/authlib/oauth2/rfc6749/grants/authorization_code.py:docstring of authlib.oauth2.rfc6749.grants.authorization_code.AuthorizationCodeGrant:1: WARNING: py:class reference target not found: authlib.oauth2.rfc6749.requests.OAuth2Request
/home/tkloczko/rpmbuild/BUILD/authlib-1.3.0/authlib/oauth2/rfc6749/grants/implicit.py:docstring of authlib.oauth2.rfc6749.grants.implicit.ImplicitGrant:1: WARNING: py:class reference target not found: authlib.oauth2.rfc6749.requests.OAuth2Request
/home/tkloczko/rpmbuild/BUILD/authlib-1.3.0/authlib/oauth2/rfc6749/grants/resource_owner_password_credentials.py:docstring of authlib.oauth2.rfc6749.grants.resource_owner_password_credentials.ResourceOwnerPasswordCredentialsGrant:1: WARNING: py:class reference target not found: authlib.oauth2.rfc6749.requests.OAuth2Request
/home/tkloczko/rpmbuild/BUILD/authlib-1.3.0/authlib/oauth2/rfc6749/grants/client_credentials.py:docstring of authlib.oauth2.rfc6749.grants.client_credentials.ClientCredentialsGrant:1: WARNING: py:class reference target not found: authlib.oauth2.rfc6749.requests.OAuth2Request
/home/tkloczko/rpmbuild/BUILD/authlib-1.3.0/authlib/oauth2/rfc6749/grants/refresh_token.py:docstring of authlib.oauth2.rfc6749.grants.refresh_token.RefreshTokenGrant:1: WARNING: py:class reference target not found: authlib.oauth2.rfc6749.requests.OAuth2Request
/home/tkloczko/rpmbuild/BUILD/authlib-1.3.0/docs/specs/rfc6750.rst:17: WARNING: py:class reference target not found: BearerTokenValidator
<unknown>:1: WARNING: py:class reference target not found: authlib.oauth2.rfc6750.token.BearerTokenGenerator
<unknown>:1: WARNING: py:class reference target not found: cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey
<unknown>:1: WARNING: py:class reference target not found: cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey
<unknown>:1: WARNING: py:class reference target not found: cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey
<unknown>:1: WARNING: py:class reference target not found: cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey
/home/tkloczko/rpmbuild/BUILD/authlib-1.3.0/authlib/jose/rfc7519/jwt.py:docstring of authlib.jose.rfc7519.jwt.JsonWebToken.decode:1: WARNING: py:meth reference target not found: verify
/home/tkloczko/rpmbuild/BUILD/authlib-1.3.0/docs/specs/rfc7523.rst:69: WARNING: py:class reference target not found: authlib.integrations.httpx_client.AssertionSession
/home/tkloczko/rpmbuild/BUILD/authlib-1.3.0/docs/specs/rfc7523.rst:70: WARNING: py:class reference target not found: authlib.integrations.httpx_client.AsyncAssertionSession
/home/tkloczko/rpmbuild/BUILD/authlib-1.3.0/authlib/oauth2/rfc7523/jwt_bearer.py:docstring of authlib.oauth2.rfc7523.jwt_bearer.JWTBearerGrant:1: WARNING: py:class reference target not found: authlib.oauth2.rfc6749.requests.OAuth2Request
/home/tkloczko/rpmbuild/BUILD/authlib-1.3.0/authlib/oauth2/rfc8628/device_code.py:docstring of authlib.oauth2.rfc8628.device_code.DeviceCodeGrant:1: WARNING: py:class reference target not found: authlib.oauth2.rfc6749.requests.OAuth2Request
/home/tkloczko/rpmbuild/BUILD/authlib-1.3.0/authlib/oauth2/rfc9068/token.py:docstring of authlib.oauth2.rfc9068.token.JWTBearerTokenGenerator:5: WARNING: py:class reference target not found: authlib.oauth2.rfc6750.token.BearerTokenGenerator
/home/tkloczko/rpmbuild/BUILD/authlib-1.3.0/authlib/oidc/core/grants/implicit.py:docstring of authlib.oidc.core.grants.implicit.OpenIDImplicitGrant:1: WARNING: py:class reference target not found: authlib.oauth2.rfc6749.requests.OAuth2Request
/home/tkloczko/rpmbuild/BUILD/authlib-1.3.0/authlib/oidc/core/grants/hybrid.py:docstring of authlib.oidc.core.grants.hybrid.OpenIDHybridGrant:1: WARNING: py:class reference target not found: authlib.oauth2.rfc6749.requests.OAuth2Request
done
build succeeded, 42 warnings.

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

[kloczek]

Closed as completed? I don't see any commit related to fix of this issue. 🤔

[lepture]

You can install the package before building the docs.

[kloczek]

You can install the package before building the docs.

Cannot do that because packaging process is done fro non-root account.
Nevertheless this issue is about sphinx warnings.
Did you try to reproduce that issue bu execute sphinx-build with -i option? 🤔