1.2.1: 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 v5.3.0

Traceback (most recent call last):
  File "/usr/lib/python3.8/site-packages/sphinx/config.py", line 350, in eval_config_file
    exec(code, namespace)
  File "/home/tkloczko/rpmbuild/BUILD/pyproject-api-1.2.1/docs/conf.py", line 5, in <module>
    from pyproject_api import __version__
ModuleNotFoundError: No module named 'pyproject_api'

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 276, 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 172, in read
    namespace = eval_config_file(filename, tags)
  File "/usr/lib/python3.8/site-packages/sphinx/config.py", line 363, 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 350, in eval_config_file
    exec(code, namespace)
  File "/home/tkloczko/rpmbuild/BUILD/pyproject-api-1.2.1/docs/conf.py", line 5, in <module>
    from pyproject_api import __version__
ModuleNotFoundError: No module named 'pyproject_api'


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 350, in eval_config_file
    exec(code, namespace)
  File "/home/tkloczko/rpmbuild/BUILD/pyproject-api-1.2.1/docs/conf.py", line 5, in <module>
    from pyproject_api import __version__

This can be fixed by patch like below:

--- a/docs/conf.py
+++ b/docs/conf.py
@@ -1,5 +1,9 @@
 from __future__ import annotations

+import sys
+import os
+sys.path.insert(0, os.path.abspath("../src"))
+
 from datetime import datetime

 from pyproject_api import __version__

This patch adds what is 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 v5.3.0
making output directory... done
building [mo]: targets for 0 po files that are out of date
building [man]: all manpages
updating environment: [new config] 2 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-pyproject-api.3 { changelog } /home/tkloczko/rpmbuild/BUILD/pyproject-api-1.2.1/src/pyproject_api/_frontend.py:docstring of pyproject_api._frontend.Frontend:1: WARNING: py:class reference target not found: abc.ABC
/home/tkloczko/rpmbuild/BUILD/pyproject-api-1.2.1/src/pyproject_api/_frontend.py:docstring of pyproject_api._frontend.Frontend.get_requires_for_build_sdist:1: WARNING: py:class reference target not found: ConfigSettings
/home/tkloczko/rpmbuild/BUILD/pyproject-api-1.2.1/src/pyproject_api/_frontend.py:docstring of pyproject_api._frontend.Frontend.get_requires_for_build_wheel:1: WARNING: py:class reference target not found: ConfigSettings
/home/tkloczko/rpmbuild/BUILD/pyproject-api-1.2.1/src/pyproject_api/_frontend.py:docstring of pyproject_api._frontend.Frontend.get_requires_for_build_editable:1: WARNING: py:class reference target not found: ConfigSettings
/home/tkloczko/rpmbuild/BUILD/pyproject-api-1.2.1/src/pyproject_api/_frontend.py:docstring of pyproject_api._frontend.Frontend.prepare_metadata_for_build_wheel:1: WARNING: py:class reference target not found: Path
/home/tkloczko/rpmbuild/BUILD/pyproject-api-1.2.1/src/pyproject_api/_frontend.py:docstring of pyproject_api._frontend.Frontend.prepare_metadata_for_build_wheel:1: WARNING: py:class reference target not found: ConfigSettings
/home/tkloczko/rpmbuild/BUILD/pyproject-api-1.2.1/src/pyproject_api/_frontend.py:docstring of pyproject_api._frontend.Frontend.prepare_metadata_for_build_editable:1: WARNING: py:class reference target not found: Path
/home/tkloczko/rpmbuild/BUILD/pyproject-api-1.2.1/src/pyproject_api/_frontend.py:docstring of pyproject_api._frontend.Frontend.prepare_metadata_for_build_editable:1: WARNING: py:class reference target not found: ConfigSettings
/home/tkloczko/rpmbuild/BUILD/pyproject-api-1.2.1/src/pyproject_api/_frontend.py:docstring of pyproject_api._frontend.Frontend.build_sdist:1: WARNING: py:class reference target not found: Path
/home/tkloczko/rpmbuild/BUILD/pyproject-api-1.2.1/src/pyproject_api/_frontend.py:docstring of pyproject_api._frontend.Frontend.build_sdist:1: WARNING: py:class reference target not found: ConfigSettings
/home/tkloczko/rpmbuild/BUILD/pyproject-api-1.2.1/src/pyproject_api/_frontend.py:docstring of pyproject_api._frontend.Frontend.build_wheel:1: WARNING: py:class reference target not found: Path
/home/tkloczko/rpmbuild/BUILD/pyproject-api-1.2.1/src/pyproject_api/_frontend.py:docstring of pyproject_api._frontend.Frontend.build_wheel:1: WARNING: py:class reference target not found: ConfigSettings
/home/tkloczko/rpmbuild/BUILD/pyproject-api-1.2.1/src/pyproject_api/_frontend.py:docstring of pyproject_api._frontend.Frontend.build_wheel:1: WARNING: py:class reference target not found: Path
/home/tkloczko/rpmbuild/BUILD/pyproject-api-1.2.1/src/pyproject_api/_frontend.py:docstring of pyproject_api._frontend.Frontend.build_editable:1: WARNING: py:class reference target not found: Path
/home/tkloczko/rpmbuild/BUILD/pyproject-api-1.2.1/src/pyproject_api/_frontend.py:docstring of pyproject_api._frontend.Frontend.build_editable:1: WARNING: py:class reference target not found: ConfigSettings
/home/tkloczko/rpmbuild/BUILD/pyproject-api-1.2.1/src/pyproject_api/_frontend.py:docstring of pyproject_api._frontend.Frontend.build_editable:1: WARNING: py:class reference target not found: Path
done
build succeeded, 16 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
sissaschool/elementpath@bf869d9e
jaraco/cssutils#21
pywbem/pywbem#2895
sissaschool/xmlschema@42ea98f2
RDFLib/rdflib#2036
frostming/unearth#14
pypa/distlib@98b9b89f

[gaborbernat]

You know the drill, make a PR if you make the issue, or don't make the issue.

[gaborbernat]

You're expected to install the project, not alter the sys.path, before running sphinx-build.