4.0.0: sphinx warnings `reference target not found`

[kloczek]

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 build/sphinx/man
Running Sphinx v4.5.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] 7 added, 0 changed, 0 removed
reading sources... [100%] usage
/home/tkloczko/rpmbuild/BUILD/sphinx-click-4.0.0/docs/changelog.rst:4: CRITICAL: Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: 'ChangeLog'.
/home/tkloczko/rpmbuild/BUILD/sphinx-click-4.0.0/docs/examples/commandcollections.rst:18: ERROR: Failed to import "cli" from "commandcollections.cli". The following exception was raised:
Traceback (most recent call last):
  File "/home/tkloczko/rpmbuild/BUILD/sphinx-click-4.0.0/sphinx_click/ext.py", line 379, in _load_module
    mod = __import__(module_name, globals(), locals(), [attr_name])
ModuleNotFoundError: No module named 'commandcollections'
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-sphinx-click.3 { installation usage contributing changelog examples/index examples/commandcollections } /home/tkloczko/rpmbuild/BUILD/sphinx-click-4.0.0/docs/index.rst:4: WARNING: py:mod reference target not found: sphinx_click
/home/tkloczko/rpmbuild/BUILD/sphinx-click-4.0.0/docs/index.rst:24: WARNING: py:mod reference target not found: click
/home/tkloczko/rpmbuild/BUILD/sphinx-click-4.0.0/docs/index.rst:23: WARNING: py:mod reference target not found: click
/home/tkloczko/rpmbuild/BUILD/sphinx-click-4.0.0/docs/index.rst:26: WARNING: py:mod reference target not found: sphinxcontrib.autoprogram
/home/tkloczko/rpmbuild/BUILD/sphinx-click-4.0.0/docs/index.rst:27: WARNING: py:mod reference target not found: argparse
done
build succeeded, 7 warnings.

[stephenfin]

Can you confirm if this was an issue with previous versions?

[kloczek]

It was et least in last 3-4 months (I had no time to report that .. sorry)

[stephenfin]

No problem. I haven't seen this issue personally (and I built all my documentation with the -W flag so I'd have noticed). If possible, could you find the specific version that this broke on? That'll give me something to work with as I try to investigate this. Alternatively, could you give me a minimal reproducer?

[stephenfin]

Oh, wait, you're referring to the docs for this project. Apologies. I'll take a look now

[kloczek]

Tested and it still needs one small patch

--- a/docs/conf.py~     2022-04-26 17:55:14.000000000 +0000
+++ b/docs/conf.py      2022-04-26 17:56:41.179553922 +0000
@@ -5,6 +5,7 @@
 import os
 import sys

+sys.path.insert(0, os.path.abspath('..'))
 sys.path.insert(0, os.path.abspath('../examples'))

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

With that patch is possible now generate documentation out of source tree and without tox (which is shorter 😄 )

+ /usr/bin/sphinx-build -n -T -b man docs build/sphinx/man
Running Sphinx v4.5.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] 7 added, 0 changed, 0 removed
reading sources... [100%] usage
/home/tkloczko/rpmbuild/BUILD/sphinx-click-4.0.0/docs/changelog.rst:4: CRITICAL: Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: 'ChangeLog'.
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-sphinx-click.3 { installation usage contributing changelog examples/index examples/commandcollections } done
build succeeded, 1 warning.

Nevertheless .. thank you 😄

[stephenfin]

Tested and it still needs one small patch

--- a/docs/conf.py~     2022-04-26 17:55:14.000000000 +0000
+++ b/docs/conf.py      2022-04-26 17:56:41.179553922 +0000
@@ -5,6 +5,7 @@
 import os
 import sys

+sys.path.insert(0, os.path.abspath('..'))
 sys.path.insert(0, os.path.abspath('../examples'))

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

With that patch is possible now generate documentation out of source tree and without tox (which is shorter smile )

Done :slightly_smiling_face:

[kloczek]

Thank you 😄