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

```console + /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/pytoolconfig-1.2.6/docs/conf.py", line 12, in from pytoolconfig._version import version ModuleNotFoundError: No module named 'pytoolconfig' 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/pytoolconfig-1.2.6/docs/conf.py", line 12, in from pytoolconfig._version import version ModuleNotFoundError: No module named 'pytoolconfig' 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/pytoolconfig-1.2.6/docs/conf.py", line 12, in from pytoolconfig._version import version ModuleNotFoundError: No module named 'pytoolconfig' ```

This can be fixed by patch like below:

--- a/docs/conf.py
+++ b/docs/conf.py
@@ -8,14 +8,15 @@

 from __future__ import annotations

-# -- Project information -----------------------------------------------------
-from pytoolconfig._version import version
-
-# -- Path setup --------------------------------------------------------------
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#
+import sys
+import os
+sys.path.insert(0, os.path.abspath("../src"))
+
+# -- Project information -----------------------------------------------------
+from pytoolconfig._version import version

 project = "pytoolconfig"
 copyright = "2023, bagel897"  # noqa: A001

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:

```console + /usr/bin/sphinx-build -n -T -b man docs build/sphinx/man Running Sphinx v7.1.2 WARNING: html_static_path entry '_static' does not exist [autosummary] generating autosummary for: api.rst, command_line.rst, documentation.rst, global_configuration.rst, index.rst, pydantic.rst, universal_config.rst [autosummary] generating autosummary for: /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.2.6/docs/generated/pytoolconfig.PyToolConfig.rst, /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.2.6/docs/generated/pytoolconfig.rst, /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.2.6/docs/generated/pytoolconfig.sources.IniConfig.rst, /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.2.6/docs/generated/pytoolconfig.sources.PyProject.rst, /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.2.6/docs/generated/pytoolconfig.sources.PyTool.rst, /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.2.6/docs/generated/pytoolconfig.sources.SetupConfig.rst, /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.2.6/docs/generated/pytoolconfig.sources.Source.rst building [mo]: targets for 0 po files that are out of date writing output... building [man]: all manpages updating environment: [new config] 14 added, 0 changed, 0 removed reading sources... [100%] universal_config WARNING: Failed guarded type import with ModuleNotFoundError("No module named '_typeshed'") looking for now-outdated files... none found pickling environment... done checking consistency... done writing... pytoolconfig.1 { command_line universal_config documentation global_configuration pydantic api generated/pytoolconfig generated/pytoolconfig.PyToolConfig generated/pytoolconfig.sources.Source generated/pytoolconfig.sources.IniConfig generated/pytoolconfig.sources.SetupConfig generated/pytoolconfig.sources.PyProject generated/pytoolconfig.sources.PyTool } /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.2.6/docs/generated/pytoolconfig.PyToolConfig.rst:22::1: WARNING: py:obj reference target not found: pytoolconfig.PyToolConfig.parse /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.2.6/docs/generated/pytoolconfig.PyToolConfig.rst:32::1: WARNING: py:obj reference target not found: pytoolconfig.PyToolConfig.arg_parser /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.2.6/docs/generated/pytoolconfig.PyToolConfig.rst:32::1: WARNING: py:obj reference target not found: pytoolconfig.PyToolConfig.fall_through /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.2.6/docs/generated/pytoolconfig.PyToolConfig.rst:32::1: WARNING: py:obj reference target not found: pytoolconfig.PyToolConfig.sources /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.2.6/docs/generated/pytoolconfig.PyToolConfig.rst:32::1: WARNING: py:obj reference target not found: pytoolconfig.PyToolConfig.tool /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.2.6/docs/generated/pytoolconfig.PyToolConfig.rst:32::1: WARNING: py:obj reference target not found: pytoolconfig.PyToolConfig.working_directory /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.2.6/docs/generated/pytoolconfig.PyToolConfig.rst:32::1: WARNING: py:obj reference target not found: pytoolconfig.PyToolConfig.model /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.2.6/docs/generated/pytoolconfig.sources.Source.rst:22::1: WARNING: py:obj reference target not found: pytoolconfig.sources.Source.parse /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.2.6/docs/generated/pytoolconfig.sources.Source.rst:28::1: WARNING: py:obj reference target not found: pytoolconfig.sources.Source.name /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.2.6/docs/generated/pytoolconfig.sources.Source.rst:28::1: WARNING: py:obj reference target not found: pytoolconfig.sources.Source.description /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.2.6/src/pytoolconfig/sources/ini.py:docstring of pytoolconfig.sources.ini.IniConfig.__init__:1: WARNING: py:class reference target not found: Path /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.2.6/docs/generated/pytoolconfig.sources.IniConfig.rst:22::1: WARNING: py:obj reference target not found: pytoolconfig.sources.IniConfig.parse /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.2.6/docs/generated/pytoolconfig.sources.IniConfig.rst:28::1: WARNING: py:obj reference target not found: pytoolconfig.sources.IniConfig.name /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.2.6/docs/generated/pytoolconfig.sources.IniConfig.rst:28::1: WARNING: py:obj reference target not found: pytoolconfig.sources.IniConfig.description /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.2.6/docs/generated/pytoolconfig.sources.SetupConfig.rst:22::1: WARNING: py:obj reference target not found: pytoolconfig.sources.SetupConfig.parse /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.2.6/docs/generated/pytoolconfig.sources.SetupConfig.rst:28::1: WARNING: py:obj reference target not found: pytoolconfig.sources.SetupConfig.description /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.2.6/docs/generated/pytoolconfig.sources.SetupConfig.rst:28::1: WARNING: py:obj reference target not found: pytoolconfig.sources.SetupConfig.name /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.2.6/docs/generated/pytoolconfig.sources.PyProject.rst:23::1: WARNING: py:obj reference target not found: pytoolconfig.sources.PyProject.parse /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.2.6/docs/generated/pytoolconfig.sources.PyProject.rst:23::1: WARNING: py:obj reference target not found: pytoolconfig.sources.PyProject.universalconfig /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.2.6/docs/generated/pytoolconfig.sources.PyProject.rst:32::1: WARNING: py:obj reference target not found: pytoolconfig.sources.PyProject.description /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.2.6/docs/generated/pytoolconfig.sources.PyProject.rst:32::1: WARNING: py:obj reference target not found: pytoolconfig.sources.PyProject.name /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.2.6/docs/generated/pytoolconfig.sources.PyProject.rst:32::1: WARNING: py:obj reference target not found: pytoolconfig.sources.PyProject.toml_dict /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.2.6/docs/generated/pytoolconfig.sources.PyProject.rst:32::1: WARNING: py:obj reference target not found: pytoolconfig.sources.PyProject.tool /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.2.6/docs/generated/pytoolconfig.sources.PyProject.rst:32::1: WARNING: py:obj reference target not found: pytoolconfig.sources.PyProject.file /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.2.6/docs/generated/pytoolconfig.sources.PyTool.rst:23::1: WARNING: py:obj reference target not found: pytoolconfig.sources.PyTool.parse /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.2.6/docs/generated/pytoolconfig.sources.PyTool.rst:23::1: WARNING: py:obj reference target not found: pytoolconfig.sources.PyTool.universalconfig /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.2.6/docs/generated/pytoolconfig.sources.PyTool.rst:32::1: WARNING: py:obj reference target not found: pytoolconfig.sources.PyTool.description /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.2.6/docs/generated/pytoolconfig.sources.PyTool.rst:32::1: WARNING: py:obj reference target not found: pytoolconfig.sources.PyTool.name /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.2.6/docs/generated/pytoolconfig.sources.PyTool.rst:32::1: WARNING: py:obj reference target not found: pytoolconfig.sources.PyTool.toml_dict /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.2.6/docs/generated/pytoolconfig.sources.PyTool.rst:32::1: WARNING: py:obj reference target not found: pytoolconfig.sources.PyTool.tool /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.2.6/docs/generated/pytoolconfig.sources.PyTool.rst:32::1: WARNING: py:obj reference target not found: pytoolconfig.sources.PyTool.file done build succeeded, 33 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

[bagel897]

Can this be run inside the venv - using pdm run sphinx-build ...? This way there's a single source of truth for the project environment, instead of using a hack.

[kloczek]

Can this be run inside the venv - using pdm run sphinx-build ...?

Yes it can be however with patch which provided nullifies necessity of such procedure. It follows KISS principle ..

[bagel897]

It modifies the sys path - it wouldn't be able to include any possible dependencies or account for changes to the layout/build-system. Using the venv also allows for a specified version of sphinx to be used along with all the correct dependencies. Is this for packaging into an RPM? If so, I can change it

[kloczek]

It modifies the sys path - it wouldn't be able to include any possible dependencies or account for changes to the layout/build-system. Using the venv also allows for a specified version of sphinx to be used along with all the correct dependencies. Is this for packaging into an RPM? If so, I can change it

• This is not only for rpm but any other packaging software (I'm using it with Solaris IPS as well) which builds software packages from non-root account and/or on system image which is 100% R/O except directory in which is unpacked source code
• Using venv on packaging usually does not make any sense because packaging is usually performed in separated build envs in which are installed only other packages listed in build dependencies. In other words such package(s) build env is OOTB virtual env.
• That patch allows build documentation without have installed module
• That patch guarantees as well that rendered documentation will be generated ageist not installed pytoolconfig but version which is in source tree.

[bagel897]

Ok, just keep in mind this package contains a sphinx plugin used in the documentation of this project. It should work, but may cause issues in the future

[bagel897]

You would need sphinx_rtd_theme, tabulate, and sphinx_autodoc_typehints to build it out of the venv currently.

[kloczek]

Just tested 1.3.1 and issue with alter sys.path is sorted out (thank you) however issue with sphinx warnings still is sorted out 😋

sphinx output:

```console + /usr/bin/sphinx-build -n -T -b man docs build/sphinx/man Running Sphinx v7.1.2 [autosummary] generating autosummary for: api.rst, command_line.rst, documentation.rst, global_configuration.rst, index.rst, pydantic.rst, universal_config.rst [autosummary] generating autosummary for: /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.3.1/docs/generated/pytoolconfig.PyToolConfig.rst, /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.3.1/docs/generated/pytoolconfig.rst, /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.3.1/docs/generated/pytoolconfig.sources.IniConfig.rst, /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.3.1/docs/generated/pytoolconfig.sources.PyProject.rst, /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.3.1/docs/generated/pytoolconfig.sources.PyTool.rst, /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.3.1/docs/generated/pytoolconfig.sources.SetupConfig.rst, /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.3.1/docs/generated/pytoolconfig.sources.Source.rst 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] 14 added, 0 changed, 0 removed reading sources... [100%] universal_config looking for now-outdated files... none found pickling environment... done checking consistency... done writing... python-pytoolconfig.3 { command_line universal_config documentation global_configuration pydantic api generated/pytoolconfig generated/pytoolconfig.PyToolConfig generated/pytoolconfig.sources.Source generated/pytoolconfig.sources.IniConfig generated/pytoolconfig.sources.SetupConfig generated/pytoolconfig.sources.PyProject generated/pytoolconfig.sources.PyTool } /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.3.1/docs/generated/pytoolconfig.PyToolConfig.rst:22::1: WARNING: py:obj reference target not found: pytoolconfig.PyToolConfig.parse /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.3.1/docs/generated/pytoolconfig.PyToolConfig.rst:32::1: WARNING: py:obj reference target not found: pytoolconfig.PyToolConfig.arg_parser /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.3.1/docs/generated/pytoolconfig.PyToolConfig.rst:32::1: WARNING: py:obj reference target not found: pytoolconfig.PyToolConfig.fall_through /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.3.1/docs/generated/pytoolconfig.PyToolConfig.rst:32::1: WARNING: py:obj reference target not found: pytoolconfig.PyToolConfig.sources /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.3.1/docs/generated/pytoolconfig.PyToolConfig.rst:32::1: WARNING: py:obj reference target not found: pytoolconfig.PyToolConfig.tool /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.3.1/docs/generated/pytoolconfig.PyToolConfig.rst:32::1: WARNING: py:obj reference target not found: pytoolconfig.PyToolConfig.working_directory /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.3.1/docs/generated/pytoolconfig.PyToolConfig.rst:32::1: WARNING: py:obj reference target not found: pytoolconfig.PyToolConfig.model /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.3.1/docs/generated/pytoolconfig.sources.Source.rst:22::1: WARNING: py:obj reference target not found: pytoolconfig.sources.Source.parse /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.3.1/docs/generated/pytoolconfig.sources.Source.rst:28::1: WARNING: py:obj reference target not found: pytoolconfig.sources.Source.name /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.3.1/docs/generated/pytoolconfig.sources.Source.rst:28::1: WARNING: py:obj reference target not found: pytoolconfig.sources.Source.description /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.3.1/docs/generated/pytoolconfig.sources.IniConfig.rst:22::1: WARNING: py:obj reference target not found: pytoolconfig.sources.IniConfig.parse /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.3.1/docs/generated/pytoolconfig.sources.IniConfig.rst:28::1: WARNING: py:obj reference target not found: pytoolconfig.sources.IniConfig.name /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.3.1/docs/generated/pytoolconfig.sources.IniConfig.rst:28::1: WARNING: py:obj reference target not found: pytoolconfig.sources.IniConfig.description /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.3.1/docs/generated/pytoolconfig.sources.SetupConfig.rst:22::1: WARNING: py:obj reference target not found: pytoolconfig.sources.SetupConfig.parse /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.3.1/docs/generated/pytoolconfig.sources.SetupConfig.rst:28::1: WARNING: py:obj reference target not found: pytoolconfig.sources.SetupConfig.description /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.3.1/docs/generated/pytoolconfig.sources.SetupConfig.rst:28::1: WARNING: py:obj reference target not found: pytoolconfig.sources.SetupConfig.name /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.3.1/docs/generated/pytoolconfig.sources.PyProject.rst:23::1: WARNING: py:obj reference target not found: pytoolconfig.sources.PyProject.parse /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.3.1/docs/generated/pytoolconfig.sources.PyProject.rst:23::1: WARNING: py:obj reference target not found: pytoolconfig.sources.PyProject.universalconfig /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.3.1/docs/generated/pytoolconfig.sources.PyProject.rst:32::1: WARNING: py:obj reference target not found: pytoolconfig.sources.PyProject.description /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.3.1/docs/generated/pytoolconfig.sources.PyProject.rst:32::1: WARNING: py:obj reference target not found: pytoolconfig.sources.PyProject.name /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.3.1/docs/generated/pytoolconfig.sources.PyProject.rst:32::1: WARNING: py:obj reference target not found: pytoolconfig.sources.PyProject.toml_dict /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.3.1/docs/generated/pytoolconfig.sources.PyProject.rst:32::1: WARNING: py:obj reference target not found: pytoolconfig.sources.PyProject.tool /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.3.1/docs/generated/pytoolconfig.sources.PyProject.rst:32::1: WARNING: py:obj reference target not found: pytoolconfig.sources.PyProject.file /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.3.1/docs/generated/pytoolconfig.sources.PyTool.rst:23::1: WARNING: py:obj reference target not found: pytoolconfig.sources.PyTool.parse /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.3.1/docs/generated/pytoolconfig.sources.PyTool.rst:23::1: WARNING: py:obj reference target not found: pytoolconfig.sources.PyTool.universalconfig /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.3.1/docs/generated/pytoolconfig.sources.PyTool.rst:32::1: WARNING: py:obj reference target not found: pytoolconfig.sources.PyTool.description /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.3.1/docs/generated/pytoolconfig.sources.PyTool.rst:32::1: WARNING: py:obj reference target not found: pytoolconfig.sources.PyTool.name /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.3.1/docs/generated/pytoolconfig.sources.PyTool.rst:32::1: WARNING: py:obj reference target not found: pytoolconfig.sources.PyTool.toml_dict /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.3.1/docs/generated/pytoolconfig.sources.PyTool.rst:32::1: WARNING: py:obj reference target not found: pytoolconfig.sources.PyTool.tool /home/tkloczko/rpmbuild/BUILD/pytoolconfig-1.3.1/docs/generated/pytoolconfig.sources.PyTool.rst:32::1: WARNING: py:obj reference target not found: pytoolconfig.sources.PyTool.file done build succeeded, 30 warnings. ```