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/source build/sphinx/man
Running Sphinx v4.5.0

Traceback (most recent call last):
  File "/usr/lib/python3.8/site-packages/sphinx/config.py", line 332, in eval_config_file
    exec(code, namespace)
  File "/home/tkloczko/rpmbuild/BUILD/sphinx-readable-theme-1.3.0/docs/source/conf.py", line 11, in <module>
    import sphinx_readable_theme
ModuleNotFoundError: No module named 'sphinx_readable_theme'

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 272, in build_main
    app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
  File "/usr/lib/python3.8/site-packages/sphinx/application.py", line 202, in __init__
    self.config = Config.read(self.confdir, confoverrides or {}, self.tags)
  File "/usr/lib/python3.8/site-packages/sphinx/config.py", line 165, in read
    namespace = eval_config_file(filename, tags)
  File "/usr/lib/python3.8/site-packages/sphinx/config.py", line 345, 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 332, in eval_config_file
    exec(code, namespace)
  File "/home/tkloczko/rpmbuild/BUILD/sphinx-readable-theme-1.3.0/docs/source/conf.py", line 11, in <module>
    import sphinx_readable_theme
ModuleNotFoundError: No module named 'sphinx_readable_theme'


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 332, in eval_config_file
    exec(code, namespace)
  File "/home/tkloczko/rpmbuild/BUILD/sphinx-readable-theme-1.3.0/docs/source/conf.py", line 11, in <module>
    import sphinx_readable_theme
ModuleNotFoundError: No module named 'sphinx_readable_theme'

This can be fixed by patch like below:

--- a/docs/source/conf.py~      2022-05-27 12:57:20.000000000 +0000
+++ b/docs/source/conf.py       2022-05-27 13:00:31.935970748 +0000
@@ -8,12 +8,11 @@
 import os
 import sys

-import sphinx_readable_theme
-
-
 # Adding this directory to the sys path, to build autodoc of example module.
+sys.path.insert(0, os.path.abspath("../.."))
 sys.path.insert(0, os.path.abspath(os.path.dirname(__file__)))

+import sphinx_readable_theme

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

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.

Here is the output with warnings:

+ /usr/bin/sphinx-build -n -T -b man docs/source build/sphinx/man
Running Sphinx v4.5.0
making output directory... done
loading intersphinx inventory from http://docs.python.org/2.7/objects.inv...
intersphinx inventory has moved: http://docs.python.org/2.7/objects.inv -> https://docs.python.org/2.7/objects.inv
building [mo]: targets for 0 po files that are out of date
building [man]: all manpages
updating environment: [new config] 1 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-sphinx-readable-heme.3 { } /home/tkloczko/rpmbuild/BUILD/sphinx-readable-theme-1.3.0/docs/source/example.py:docstring of example:3: WARNING: py:class reference target not found: Storage
/home/tkloczko/rpmbuild/BUILD/sphinx-readable-theme-1.3.0/docs/source/example.py:docstring of example:3: WARNING: py:func reference target not found: store_integers
done
build succeeded, 2 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