1.8.1: sphinx nitpick 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 doc build/sphinx/man
Running Sphinx v7.3.7

Traceback (most recent call last):
  File "/usr/lib/python3.10/site-packages/sphinx/config.py", line 509, in eval_config_file
    exec(code, namespace)  # NoQA: S102
  File "/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/conf.py", line 10, in <module>
    import pooch
ModuleNotFoundError: No module named 'pooch'

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

Traceback (most recent call last):
  File "/usr/lib/python3.10/site-packages/sphinx/cmd/build.py", line 332, in build_main
    app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
  File "/usr/lib/python3.10/site-packages/sphinx/application.py", line 211, in __init__
    self.config = Config.read(self.confdir, confoverrides or {}, self.tags)
  File "/usr/lib/python3.10/site-packages/sphinx/config.py", line 309, in read
    namespace = eval_config_file(filename, tags)
  File "/usr/lib/python3.10/site-packages/sphinx/config.py", line 522, 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.10/site-packages/sphinx/config.py", line 509, in eval_config_file
    exec(code, namespace)  # NoQA: S102
  File "/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/conf.py", line 10, in <module>
    import pooch
ModuleNotFoundError: No module named 'pooch'

This can be fixed by patch like below:

--- a/doc/conf.py
+++ b/doc/conf.py
@@ -5,10 +5,12 @@
 # This code is part of the Fatiando a Terra project (https://www.fatiando.org)
 #
 import os
+import sys
 import datetime

-import pooch
+sys.path.insert(0, os.path.abspath(".."))

+import pooch

 # Project information
 # -----------------------------------------------------------------------------

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 doc build/sphinx/man
Running Sphinx v7.3.7
making output directory... done
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
loading intersphinx inventory from http://pandas.pydata.org/pandas-docs/stable/objects.inv...
loading intersphinx inventory from https://requests.readthedocs.io/en/latest/objects.inv...
building [mo]: targets for 0 po files that are out of date
writing output...
building [man]: all manpages
updating environment: [new config] 23 added, 0 changed, 0 removed
reading sources... [100%] versions
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/api/index.rst:20: WARNING: autosummary: stub file not found 'pooch.create'. Check your autosummary_generate setting.
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/api/index.rst:20: WARNING: autosummary: stub file not found 'pooch.Pooch'. Check your autosummary_generate setting.
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/api/index.rst:20: WARNING: autosummary: stub file not found 'pooch.retrieve'. Check your autosummary_generate setting.
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/api/index.rst:30: WARNING: autosummary: stub file not found 'pooch.os_cache'. Check your autosummary_generate setting.
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/api/index.rst:30: WARNING: autosummary: stub file not found 'pooch.make_registry'. Check your autosummary_generate setting.
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/api/index.rst:30: WARNING: autosummary: stub file not found 'pooch.file_hash'. Check your autosummary_generate setting.
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/api/index.rst:30: WARNING: autosummary: stub file not found 'pooch.check_version'. Check your autosummary_generate setting.
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/api/index.rst:30: WARNING: autosummary: stub file not found 'pooch.get_logger'. Check your autosummary_generate setting.
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/api/index.rst:42: WARNING: autosummary: stub file not found 'pooch.HTTPDownloader'. Check your autosummary_generate setting.
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/api/index.rst:42: WARNING: autosummary: stub file not found 'pooch.FTPDownloader'. Check your autosummary_generate setting.
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/api/index.rst:42: WARNING: autosummary: stub file not found 'pooch.SFTPDownloader'. Check your autosummary_generate setting.
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/api/index.rst:42: WARNING: autosummary: stub file not found 'pooch.DOIDownloader'. Check your autosummary_generate setting.
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/api/index.rst:53: WARNING: autosummary: stub file not found 'pooch.Unzip'. Check your autosummary_generate setting.
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/api/index.rst:53: WARNING: autosummary: stub file not found 'pooch.Untar'. Check your autosummary_generate setting.
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/api/index.rst:53: WARNING: autosummary: stub file not found 'pooch.Decompress'. Check your autosummary_generate setting.
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/api/index.rst:63: WARNING: autosummary: stub file not found 'pooch.test'. Check your autosummary_generate setting.
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-pooch.3 { about install retrieve multiple-files sample-data hashes user-defined-cache registry-files multiple-urls protocols logging downloaders processors authentication progressbars unpacking decompressing api/index compatibility citing changes versions } /home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/install.rst:72: WARNING: py:class reference target not found: pooch.SFTPDownloader
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/retrieve.rst:9: WARNING: py:func reference target not found: pooch.retrieve
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/retrieve.rst:25: WARNING: py:func reference target not found: pooch.os_cache
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/retrieve.rst:62: WARNING: py:func reference target not found: pooch.retrieve
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/retrieve.rst:79: WARNING: py:func reference target not found: pooch.retrieve
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/retrieve.rst:91: WARNING: py:class reference target not found: pooch.Pooch
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/multiple-files.rst:19: WARNING: py:func reference target not found: pooch.create
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/multiple-files.rst:37: WARNING: py:class reference target not found: pooch.Pooch
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/multiple-files.rst:80: WARNING: py:meth reference target not found: pooch.Pooch.fetch
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/multiple-files.rst:100: WARNING: py:class reference target not found: pooch.Pooch
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/multiple-files.rst:105: WARNING: py:func reference target not found: pooch.create
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/multiple-files.rst:115: WARNING: py:meth reference target not found: pooch.Pooch.fetch
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/sample-data.rst:55: WARNING: py:func reference target not found: pooch.create
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/sample-data.rst:55: WARNING: py:func reference target not found: pooch.Pooch
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/sample-data.rst:115: WARNING: py:func reference target not found: pooch.create
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/sample-data.rst:115: WARNING: py:class reference target not found: pooch.Pooch
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/sample-data.rst:115: WARNING: py:meth reference target not found: pooch.Pooch.fetch
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/sample-data.rst:124: WARNING: py:func reference target not found: pooch.os_cache
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/sample-data.rst:155: WARNING: py:func reference target not found: pooch.create
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/sample-data.rst:155: WARNING: py:meth reference target not found: pooch.Pooch.fetch
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/sample-data.rst:180: WARNING: py:func reference target not found: pooch.create
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/hashes.rst:28: WARNING: py:func reference target not found: pooch.file_hash
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/hashes.rst:58: WARNING: py:func reference target not found: pooch.create
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/hashes.rst:58: WARNING: py:func reference target not found: pooch.retrieve
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/user-defined-cache.rst:6: WARNING: py:func reference target not found: pooch.create
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/registry-files.rst:9: WARNING: py:meth reference target not found: pooch.Pooch.load_registry
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/registry-files.rst:96: WARNING: py:func reference target not found: pooch.make_registry
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/registry-files.rst:109: WARNING: py:func reference target not found: pooch.retrieve
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/registry-files.rst:115: WARNING: py:func reference target not found: pooch.retrieve
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/registry-files.rst:115: WARNING: py:func reference target not found: pooch.make_registry
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/registry-files.rst:142: WARNING: py:func reference target not found: pooch.retrieve
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/multiple-urls.rst:6: WARNING: py:func reference target not found: pooch.create
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/multiple-urls.rst:64: WARNING: py:meth reference target not found: pooch.Pooch.load_registry
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/protocols.rst:59: WARNING: py:class reference target not found: pooch.DOIDownloader
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/protocols.rst:62: WARNING: py:func reference target not found: pooch.retrieve
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/protocols.rst:74: WARNING: py:class reference target not found: pooch.Pooch
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/protocols.rst:107: WARNING: py:meth reference target not found: pooch.Pooch.load_registry_from_doi
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/downloaders.rst:6: WARNING: py:meth reference target not found: pooch.Pooch.fetch
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/downloaders.rst:6: WARNING: py:meth reference target not found: pooch.retrieve
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/downloaders.rst:6: WARNING: py:meth reference target not found: pooch.Pooch.fetch
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/downloaders.rst:6: WARNING: py:meth reference target not found: pooch.retrieve
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/downloaders.rst:51: WARNING: py:meth reference target not found: pooch.Pooch.fetch
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/downloaders.rst:51: WARNING: py:func reference target not found: pooch.retrieve
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/downloaders.rst:88: WARNING: py:meth reference target not found: pooch.Pooch.is_available
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/downloaders.rst:124: WARNING: py:meth reference target not found: pooch.Pooch.is_available
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/processors.rst:6: WARNING: py:meth reference target not found: pooch.Pooch.fetch
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/processors.rst:6: WARNING: py:func reference target not found: pooch.retrieve
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/processors.rst:61: WARNING: py:class reference target not found: pooch.Unzip
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/authentication.rst:9: WARNING: py:class reference target not found: pooch.HTTPDownloader
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/authentication.rst:53: WARNING: py:class reference target not found: pooch.FTPDownloader
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/authentication.rst:53: WARNING: py:class reference target not found: pooch.SFTPDownloader
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/progressbars.rst:11: WARNING: py:func reference target not found: pooch.retrieve
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/progressbars.rst:32: WARNING: py:meth reference target not found: pooch.Pooch.fetch
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/progressbars.rst:76: WARNING: py:class reference target not found: pooch.HTTPDownloader
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/unpacking.rst:6: WARNING: py:class reference target not found: pooch.Unzip
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/unpacking.rst:6: WARNING: py:class reference target not found: pooch.Untar
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/unpacking.rst:35: WARNING: py:class reference target not found: pooch.Unzip
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/unpacking.rst:35: WARNING: py:class reference target not found: pooch.Untar
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/unpacking.rst:75: WARNING: py:class reference target not found: pooch.Untar
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/decompressing.rst:6: WARNING: py:class reference target not found: pooch.Decompress
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/decompressing.rst:30: WARNING: py:class reference target not found: pooch.Decompress
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/api/index.rst:26:<autosummary>:1: WARNING: py:obj reference target not found: pooch.create
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/api/index.rst:26:<autosummary>:1: WARNING: py:class reference target not found: pooch.Pooch
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/api/index.rst:26:<autosummary>:1: WARNING: py:obj reference target not found: pooch.Pooch
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/api/index.rst:26:<autosummary>:1: WARNING: py:obj reference target not found: pooch.retrieve
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/api/index.rst:38:<autosummary>:1: WARNING: py:obj reference target not found: pooch.os_cache
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/api/index.rst:38:<autosummary>:1: WARNING: py:obj reference target not found: pooch.make_registry
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/api/index.rst:38:<autosummary>:1: WARNING: py:obj reference target not found: pooch.file_hash
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/api/index.rst:38:<autosummary>:1: WARNING: py:obj reference target not found: pooch.check_version
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/api/index.rst:38:<autosummary>:1: WARNING: py:obj reference target not found: pooch.get_logger
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/api/index.rst:49:<autosummary>:1: WARNING: py:obj reference target not found: pooch.HTTPDownloader
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/api/index.rst:49:<autosummary>:1: WARNING: py:obj reference target not found: pooch.FTPDownloader
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/api/index.rst:49:<autosummary>:1: WARNING: py:obj reference target not found: pooch.SFTPDownloader
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/api/index.rst:49:<autosummary>:1: WARNING: py:obj reference target not found: pooch.DOIDownloader
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/api/index.rst:59:<autosummary>:1: WARNING: py:obj reference target not found: pooch.Unzip
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/api/index.rst:59:<autosummary>:1: WARNING: py:obj reference target not found: pooch.Untar
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/api/index.rst:59:<autosummary>:1: WARNING: py:obj reference target not found: pooch.Decompress
/home/tkloczko/rpmbuild/BUILD/pooch-1.8.1/doc/api/index.rst:66:<autosummary>:1: WARNING: py:obj reference target not found: pooch.test
done
build succeeded, 94 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

[leouieda]

First of all currently it is not possible to use straight sphinx-build command to build documentation out of source tree

Yes, which is why we recommend in our dev instructions to first install the project with python -m pip install -e .. I find this better than manipulating the path in general.

on building my packages I'm using sphinx-build command with -n switch which shows warmings about missing references. These are not critical issues.

Thanks for reporting! I didn't know about the -n switch and will check it out.