2.4.1: sphinx warnings reference target not found

[kloczek]

First of all currently on 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.2.6
building [mo]: targets for 0 po files that are out of date
writing output...
building [man]: all manpages
updating environment: [new config] 3 added, 0 changed, 0 removed
reading sources... [100%] user-guide
WARNING: autodoc: failed to import module 'asttokens'; the following exception was raised:
No module named 'asttokens'
WARNING: autodoc: failed to import class 'ASTTokens' from module 'asttokens'; the following exception was raised:
No module named 'asttokens'
WARNING: autodoc: failed to import class 'ASTText' from module 'asttokens'; the following exception was raised:
No module named 'asttokens'
WARNING: autodoc: failed to import class 'LineNumbers' from module 'asttokens'; the following exception was raised:
No module named 'asttokens'
WARNING: autodoc: failed to import module 'util' from module 'asttokens'; the following exception was raised:
No module named 'asttokens'
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-asttokens.3 { user-guide api-index } done
build succeeded, 5 warnings.

This can be fixed by patch like below:

--- a/docs/conf.py
+++ b/docs/conf.py
@@ -3,6 +3,10 @@
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html

+import sys
+import os
+sys.path.insert(0, os.path.abspath(".."))
+
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

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 v7.2.6
building [mo]: targets for 0 po files that are out of date
writing output...
building [man]: all manpages
updating environment: [new config] 3 added, 0 changed, 0 removed
reading sources... [100%] user-guide
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-asttokens.3 { user-guide api-index } /home/tkloczko/rpmbuild/BUILD/asttokens-2.4.1/asttokens/asttokens.py:docstring of asttokens.asttokens.ASTTokens:1: WARNING: py:class reference target not found: Module
/home/tkloczko/rpmbuild/BUILD/asttokens-2.4.1/asttokens/asttokens.py:docstring of asttokens.asttokens.ASTTokens:1: WARNING: py:class reference target not found: TokenInfo
/home/tkloczko/rpmbuild/BUILD/asttokens-2.4.1/asttokens/asttokens.py:docstring of asttokens.asttokens.ASTTokens.get_text_positions:1: WARNING: py:class reference target not found: AstNode
/home/tkloczko/rpmbuild/BUILD/asttokens-2.4.1/asttokens/asttokens.py:docstring of asttokens.asttokens.ASTTokens.get_tokens:1: WARNING: py:class reference target not found: AstNode
/home/tkloczko/rpmbuild/BUILD/asttokens-2.4.1/asttokens/asttokens.py:docstring of asttokens.asttokens.ASTTokens.mark_tokens:1: WARNING: py:class reference target not found: ast.Module
/home/tkloczko/rpmbuild/BUILD/asttokens-2.4.1/asttokens/asttokens.py:docstring of asttokens.asttokens.ASTTokens.token_range:1: WARNING: py:class reference target not found: collections.abc.Iterator
/home/tkloczko/rpmbuild/BUILD/asttokens-2.4.1/asttokens/asttokens.py:docstring of asttokens.ASTTokens.tree:1: WARNING: py:class reference target not found: ast.Module
/home/tkloczko/rpmbuild/BUILD/asttokens-2.4.1/asttokens/asttokens.py:docstring of asttokens.asttokens.ASTText:1: WARNING: py:class reference target not found: ast.Module
/home/tkloczko/rpmbuild/BUILD/asttokens-2.4.1/asttokens/asttokens.py:docstring of asttokens.asttokens.ASTText.get_text_positions:1: WARNING: py:class reference target not found: AstNode
/home/tkloczko/rpmbuild/BUILD/asttokens-2.4.1/asttokens/util.py:docstring of asttokens.util.visit_tree:1: WARNING: py:class reference target not found: Module
/home/tkloczko/rpmbuild/BUILD/asttokens-2.4.1/asttokens/util.py:docstring of asttokens.util.visit_tree:1: WARNING: py:class reference target not found: AstNode
/home/tkloczko/rpmbuild/BUILD/asttokens-2.4.1/asttokens/util.py:docstring of asttokens.util.visit_tree:1: WARNING: py:class reference target not found: AstNode
/home/tkloczko/rpmbuild/BUILD/asttokens-2.4.1/asttokens/util.py:docstring of asttokens.util.walk:1: WARNING: py:class reference target not found: AST
/home/tkloczko/rpmbuild/BUILD/asttokens-2.4.1/asttokens/util.py:docstring of asttokens.util.walk:1: WARNING: py:class reference target not found: Module
/home/tkloczko/rpmbuild/BUILD/asttokens-2.4.1/asttokens/util.py:docstring of asttokens.util.walk:1: WARNING: py:class reference target not found: AstNode
done
build succeeded, 15 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