3.1.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.2.6

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

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

Traceback (most recent call last):
  File "/usr/lib/python3.9/site-packages/sphinx/cmd/build.py", line 293, in build_main
    app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
  File "/usr/lib/python3.9/site-packages/sphinx/application.py", line 211, in __init__
    self.config = Config.read(self.confdir, confoverrides or {}, self.tags)
  File "/usr/lib/python3.9/site-packages/sphinx/config.py", line 181, in read
    namespace = eval_config_file(filename, tags)
  File "/usr/lib/python3.9/site-packages/sphinx/config.py", line 371, 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.9/site-packages/sphinx/config.py", line 358, in eval_config_file
    exec(code, namespace)  # NoQA: S102
  File "/home/tkloczko/rpmbuild/BUILD/versioningit-3.1.0/docs/conf.py", line 1, in <module>
    from versioningit import __version__
ModuleNotFoundError: No module named 'versioningit'


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

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

This can be fixed by patch like below:

--- a/docs/conf.py
+++ b/docs/conf.py
@@ -1,3 +1,7 @@
+import sys
+import os
+sys.path.insert(0, os.path.abspath("../src"))
+
 from versioningit import __version__

 project = "versioningit"

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
making output directory... done
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
building [mo]: targets for 0 po files that are out of date
writing output...
building [man]: all manpages
updating environment: [new config] 10 added, 0 changed, 0 removed
reading sources... [100%] writing-methods
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-versioningit.3 { how configuration runtime-version hatch command api writing-methods notes changelog } /home/tkloczko/rpmbuild/BUILD/versioningit-3.1.0/docs/configuration.rst:36: WARNING: py:obj reference target not found: my_next_version()
/home/tkloczko/rpmbuild/BUILD/versioningit-3.1.0/docs/configuration.rst:585: WARNING: py:obj reference target not found: setup()
/home/tkloczko/rpmbuild/BUILD/versioningit-3.1.0/docs/configuration.rst:752: WARNING: 'envvar' reference target not found: VERSIONINGIT_LOG_LEVEL
/home/tkloczko/rpmbuild/BUILD/versioningit-3.1.0/docs/runtime-version.rst:8: WARNING: py:obj reference target not found: importlib.metadata.version()
/home/tkloczko/rpmbuild/BUILD/versioningit-3.1.0/docs/command.rst:38: WARNING: 'envvar' reference target not found: VERSIONINGIT_LOG_LEVEL
/home/tkloczko/rpmbuild/BUILD/versioningit-3.1.0/docs/command.rst:38: WARNING: 'envvar' reference target not found: VERSIONINGIT_LOG_LEVEL
/home/tkloczko/rpmbuild/BUILD/versioningit-3.1.0/src/versioningit/core.py:docstring of versioningit.core.get_version:1: WARNING: py:class reference target not found: Path
/home/tkloczko/rpmbuild/BUILD/versioningit-3.1.0/src/versioningit/core.py:docstring of versioningit.core.get_next_version:1: WARNING: py:class reference target not found: Path
/home/tkloczko/rpmbuild/BUILD/versioningit-3.1.0/src/versioningit/get_cmdclasses.py:docstring of versioningit.get_cmdclasses.get_cmdclasses:1: WARNING: py:class reference target not found: Command
/home/tkloczko/rpmbuild/BUILD/versioningit-3.1.0/src/versioningit/get_cmdclasses.py:docstring of versioningit.get_cmdclasses.get_cmdclasses:1: WARNING: py:class reference target not found: Command
/home/tkloczko/rpmbuild/BUILD/versioningit-3.1.0/src/versioningit/get_cmdclasses.py:docstring of versioningit.get_cmdclasses.get_cmdclasses:3: WARNING: py:obj reference target not found: Command
/home/tkloczko/rpmbuild/BUILD/versioningit-3.1.0/src/versioningit/get_cmdclasses.py:docstring of versioningit.get_cmdclasses.get_cmdclasses:3: WARNING: py:obj reference target not found: setuptools.setup()
/home/tkloczko/rpmbuild/BUILD/versioningit-3.1.0/src/versioningit/get_cmdclasses.py:docstring of versioningit.get_cmdclasses.get_cmdclasses:3: WARNING: py:obj reference target not found: setuptools.command.sdist.sdist
/home/tkloczko/rpmbuild/BUILD/versioningit-3.1.0/src/versioningit/get_cmdclasses.py:docstring of versioningit.get_cmdclasses.get_cmdclasses:3: WARNING: py:obj reference target not found: setuptools.command.build_py.build_py
/home/tkloczko/rpmbuild/BUILD/versioningit-3.1.0/docs/api.rst:17: WARNING: py:obj reference target not found: setuptools.command.sdist.sdist
/home/tkloczko/rpmbuild/BUILD/versioningit-3.1.0/docs/api.rst:26: WARNING: py:obj reference target not found: setuptools.command.build_py.build_py
/home/tkloczko/rpmbuild/BUILD/versioningit-3.1.0/src/versioningit/core.py:docstring of versioningit.core.Versioningit.from_project_dir:1: WARNING: py:class reference target not found: Path
/home/tkloczko/rpmbuild/BUILD/versioningit-3.1.0/src/versioningit/core.py:docstring of versioningit.core.get_version_from_pkg_info:1: WARNING: py:class reference target not found: Path
/home/tkloczko/rpmbuild/BUILD/versioningit-3.1.0/src/versioningit/core.py:docstring of versioningit.core.run_onbuild:1: WARNING: py:class reference target not found: Path
/home/tkloczko/rpmbuild/BUILD/versioningit-3.1.0/src/versioningit/core.py:docstring of versioningit.core.run_onbuild:1: WARNING: py:class reference target not found: Path
/home/tkloczko/rpmbuild/BUILD/versioningit-3.1.0/src/versioningit/core.py:docstring of versioningit.core.get_template_fields_from_distribution:1: WARNING: py:class reference target not found: Distribution
/home/tkloczko/rpmbuild/BUILD/versioningit-3.1.0/src/versioningit/core.py:docstring of versioningit.core.get_template_fields_from_distribution:1: WARNING: py:obj reference target not found: setuptools.Distribution
/home/tkloczko/rpmbuild/BUILD/versioningit-3.1.0/docs/writing-methods.rst:29: WARNING: py:obj reference target not found: my_vcs()
/home/tkloczko/rpmbuild/BUILD/versioningit-3.1.0/docs/writing-methods.rst:38: WARNING: py:obj reference target not found: setup()
/home/tkloczko/rpmbuild/BUILD/versioningit-3.1.0/docs/writing-methods.rst:38: WARNING: py:obj reference target not found: setup()
/home/tkloczko/rpmbuild/BUILD/versioningit-3.1.0/docs/writing-methods.rst:55: WARNING: py:class reference target not found: path
/home/tkloczko/rpmbuild/BUILD/versioningit-3.1.0/docs/writing-methods.rst:152: WARNING: py:class reference target not found: path
/home/tkloczko/rpmbuild/BUILD/versioningit-3.1.0/src/versioningit/onbuild.py:docstring of versioningit.onbuild.OnbuildFileProvider.get_file:1: WARNING: py:class reference target not found: PurePath
/home/tkloczko/rpmbuild/BUILD/versioningit-3.1.0/src/versioningit/onbuild.py:docstring of versioningit.onbuild.OnbuildFileProvider.get_file:1: WARNING: py:class reference target not found: PurePath
/home/tkloczko/rpmbuild/BUILD/versioningit-3.1.0/src/versioningit/onbuild.py:docstring of versioningit.onbuild.OnbuildFile.open:1: WARNING: py:class reference target not found: TextMode
/home/tkloczko/rpmbuild/BUILD/versioningit-3.1.0/src/versioningit/onbuild.py:docstring of versioningit.onbuild.OnbuildFile.open:1: WARNING: py:class reference target not found: BinaryMode
/home/tkloczko/rpmbuild/BUILD/versioningit-3.1.0/docs/writing-methods.rst:205: WARNING: py:obj reference target not found: foobar_vcs()
/home/tkloczko/rpmbuild/BUILD/versioningit-3.1.0/docs/notes.rst:21: WARNING: py:obj reference target not found: importlib.metadata.version()
/home/tkloczko/rpmbuild/BUILD/versioningit-3.1.0/docs/notes.rst:21: WARNING: py:obj reference target not found: importlib.metadata.version()
/home/tkloczko/rpmbuild/BUILD/versioningit-3.1.0/docs/changelog.rst:102: WARNING: 'envvar' reference target not found: SOURCE_DATE_EPOCH
/home/tkloczko/rpmbuild/BUILD/versioningit-3.1.0/docs/changelog.rst:102: WARNING: 'envvar' reference target not found: SOURCE_DATE_EPOCH
/home/tkloczko/rpmbuild/BUILD/versioningit-3.1.0/docs/changelog.rst:139: WARNING: 'envvar' reference target not found: VERSIONINGIT_LOG_LEVEL
/home/tkloczko/rpmbuild/BUILD/versioningit-3.1.0/docs/changelog.rst:187: WARNING: py:obj reference target not found: importlib.metadata.entry_points()
/home/tkloczko/rpmbuild/BUILD/versioningit-3.1.0/docs/writing-methods.rst:215: WARNING: "unsupported "label"
/home/tkloczko/rpmbuild/BUILD/versioningit-3.1.0/docs/writing-methods.rst:223: WARNING: "unsupported "label"
/home/tkloczko/rpmbuild/BUILD/versioningit-3.1.0/docs/index.rst:79: WARNING: "unsupported "label"
/home/tkloczko/rpmbuild/BUILD/versioningit-3.1.0/docs/index.rst:90: WARNING: "unsupported "label"
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

[jwodder]

@kloczek

• The docs are intended to be built inside an environment in which versioningit has already been installed, and thus there would be no need for fiddling with sys.path. You can see such a build configuration in the [testenv:docs] environment in tox.ini (tox installs the package by default) and in the .readthedocs.yaml file (which includes instructions to install . before building the docs).

• As to the nitpicky warnings, I do not consider these to be a problem worth fixing.

[kloczek]

This issue has nothing to do with git or is this module is installed or not.

Crucial think exposing this issue is use -n option in shphinx-build execution params.

I'm not affected by those warnings because on packaging I'm rendering roff output (AKA man page). however in case of html, pdf, qca and few other hypertext formats exact parts of the text are only highlighted without '` links.
Text is OK however because sphinx cannot identify refs it is not able to add those links.

[jwodder]

@kloczek

This issue has nothing to do with git or is this module is installed or not.

My first bullet point in my previous comment was in reply to the initial portion of the issue description, regarding building the docs directly from the source tree.

---

Regarding the rest of your response, I still fail to see a problem here that is worth me investing time into fixing.