1.5.0: sphinx warnings reference target not found

[kloczek]

First of all currently on use sphinx-build command to build documentation out of source tree sphinx cannot find pytest-subprocess code

+ /usr/bin/sphinx-build -n -T -b man docs build/sphinx/man
Running Sphinx v7.2.6
WARNING:root:Generated changelog file to history.rst
making output directory... done
building [mo]: targets for 0 po files that are out of date
writing output...
building [man]: all manpages
updating environment: [new config] 4 added, 0 changed, 0 removed
reading sources... [100%] usage
WARNING: autodoc: failed to import class 'fake_process.FakeProcess' from module 'pytest_subprocess'; the following exception was raised:
No module named 'pytest_subprocess'
WARNING: autodoc: failed to import class 'utils.Any' from module 'pytest_subprocess'; the following exception was raised:
No module named 'pytest_subprocess'
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-pytest-subprocess.3 { usage api history } done
build succeeded, 2 warnings.

This can be fixed by patch like below:

--- a/docs/conf.py
+++ b/docs/conf.py
@@ -8,9 +8,10 @@
 # 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 os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
+sys.path.insert(0, os.path.abspath(".."))
+
 import datetime
 from pathlib import Path

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
WARNING:root:Generated changelog file to history.rst
making output directory... done
building [mo]: targets for 0 po files that are out of date
writing output...
building [man]: all manpages
updating environment: [new config] 4 added, 0 changed, 0 removed
reading sources... [100%] usage
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-pytest-subprocess.3 { usage api history } <unknown>:1: WARNING: py:data reference target not found: typing.Union
<unknown>:1: WARNING: py:class reference target not found: collections.abc.Sequence
<unknown>:1: WARNING: py:data reference target not found: typing.Union
<unknown>:1: WARNING: py:class reference target not found: os.PathLike
<unknown>:1: WARNING: py:class reference target not found: pytest_subprocess.utils.Program
<unknown>:1: WARNING: py:class reference target not found: pytest_subprocess.utils.Command
<unknown>:1: WARNING: py:data reference target not found: typing.Union
<unknown>:1: WARNING: py:class reference target not found: collections.abc.Sequence
<unknown>:1: WARNING: py:data reference target not found: typing.Union
<unknown>:1: WARNING: py:class reference target not found: os.PathLike
<unknown>:1: WARNING: py:class reference target not found: pytest_subprocess.utils.Program
<unknown>:1: WARNING: py:class reference target not found: pytest_subprocess.utils.Command
<unknown>:1: WARNING: py:class reference target not found: pytest_subprocess.utils.Program
<unknown>:1: WARNING: py:data reference target not found: typing.Union
<unknown>:1: WARNING: py:class reference target not found: collections.abc.Sequence
<unknown>:1: WARNING: py:data reference target not found: typing.Union
<unknown>:1: WARNING: py:class reference target not found: os.PathLike
<unknown>:1: WARNING: py:class reference target not found: pytest_subprocess.utils.Program
<unknown>:1: WARNING: py:class reference target not found: pytest_subprocess.utils.Command
<unknown>:1: WARNING: py:data reference target not found: typing.Union
<unknown>:1: WARNING: py:class reference target not found: collections.abc.Sequence
<unknown>:1: WARNING: py:data reference target not found: typing.Union
<unknown>:1: WARNING: py:data reference target not found: typing.Union
<unknown>:1: WARNING: py:class reference target not found: collections.abc.Sequence
<unknown>:1: WARNING: py:data reference target not found: typing.Union
<unknown>:1: WARNING: py:data reference target not found: typing.Optional
<unknown>:1: WARNING: py:data reference target not found: typing.Optional
<unknown>:1: WARNING: py:class reference target not found: collections.abc.Callable
<unknown>:1: WARNING: py:data reference target not found: typing.Optional
<unknown>:1: WARNING: py:data reference target not found: typing.Any
<unknown>:1: WARNING: py:data reference target not found: typing.Optional
<unknown>:1: WARNING: py:class reference target not found: collections.abc.Callable
<unknown>:1: WARNING: py:data reference target not found: typing.Optional
<unknown>:1: WARNING: py:class reference target not found: collections.abc.Callable
<unknown>:1: WARNING: py:class reference target not found: pytest_subprocess.process_recorder.ProcessRecorder
<unknown>:1: WARNING: py:data reference target not found: typing.Union
<unknown>:1: WARNING: py:class reference target not found: collections.abc.Sequence
<unknown>:1: WARNING: py:data reference target not found: typing.Union
<unknown>:1: WARNING: py:class reference target not found: os.PathLike
<unknown>:1: WARNING: py:class reference target not found: pytest_subprocess.utils.Program
<unknown>:1: WARNING: py:class reference target not found: pytest_subprocess.utils.Command
<unknown>:1: WARNING: py:data reference target not found: typing.Union
<unknown>:1: WARNING: py:class reference target not found: collections.abc.Sequence
<unknown>:1: WARNING: py:data reference target not found: typing.Union
<unknown>:1: WARNING: py:data reference target not found: typing.Union
<unknown>:1: WARNING: py:class reference target not found: collections.abc.Sequence
<unknown>:1: WARNING: py:data reference target not found: typing.Union
<unknown>:1: WARNING: py:data reference target not found: typing.Optional
<unknown>:1: WARNING: py:data reference target not found: typing.Optional
<unknown>:1: WARNING: py:class reference target not found: collections.abc.Callable
<unknown>:1: WARNING: py:data reference target not found: typing.Optional
<unknown>:1: WARNING: py:data reference target not found: typing.Any
<unknown>:1: WARNING: py:data reference target not found: typing.Optional
<unknown>:1: WARNING: py:class reference target not found: collections.abc.Callable
<unknown>:1: WARNING: py:data reference target not found: typing.Optional
<unknown>:1: WARNING: py:class reference target not found: collections.abc.Callable
<unknown>:1: WARNING: py:class reference target not found: pytest_subprocess.process_recorder.ProcessRecorder
<unknown>:1: WARNING: py:data reference target not found: typing.Optional
<unknown>:1: WARNING: py:data reference target not found: typing.Optional
done
build succeeded, 59 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

[aklajnert]

@kloczek - thanks for letting me know, I've applied your patch, let me know in case it didn't work.

[kloczek]

Thank you 👍 😄
Yep building documentation works now.
What about those nitpick warnings? 😋

[aklajnert]

Honestly, they are super unhelpful in terms of where to look into the code to fix them, and the docs are building correctly. I'd just ignore them.

[kloczek]

Those warnings are affecting output.
In case of html, pdf and few other some parts of text are only highlighted and in case html are not added <href> links.
So text is correct but actual functionality of f some documents are kind of degraded.

[aklajnert]

I don't know how do I fix these warnings, these message don't help much.