2.18.1: sphinx warnings `reference target not found`

[kloczek]

Zarr version

2.18.1

Numcodecs version

0.12.1

Python Version

3.10.14

Operating System

Linux

Installation

From autogenerated from git tag tar ball.

Description

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 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/zarr-python-2.18.1/docs/conf.py", line 24, in <module>
    import zarr
ModuleNotFoundError: No module named 'zarr'

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/zarr-python-2.18.1/docs/conf.py", line 24, in <module>
    import zarr
ModuleNotFoundError: No module named 'zarr'


Configuration error:
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/zarr-python-2.18.1/docs/conf.py", line 24, in <module>
    import zarr
ModuleNotFoundError: No module named 'zarr'

This can be fixed by patch like below:

--- a/docs/conf.py
+++ b/docs/conf.py
@@ -16,6 +16,11 @@
 import os
 import sys

+# 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.
+sys.path.append(os.path.abspath(".."))
+
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
@@ -23,12 +28,6 @@
 # The short X.Y version.
 import zarr

-# 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.
-sys.path.append(os.path.abspath(".."))
-
-
 # -- General configuration ------------------------------------------------

 # If your documentation needs a minimal Sphinx version, state it here.

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

Please let me know if you want this as PR.

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:

+ /usr/bin/sphinx-build -n -T -b man docs build/sphinx/man
Running Sphinx v7.3.7
making output directory... done
[autosummary] generating autosummary for: acknowledgments.rst, api.rst, api/attrs.rst, api/codecs.rst, api/convenience.rst, api/core.rst, api/creation.rst, api/hierarchy.rst, api/n5.rst, api/storage.rst, ..., getting_started.rst, index.rst, installation.rst, license.rst, release.rst, spec.rst, spec/v1.rst, spec/v2.rst, spec/v3.rst, tutorial.rst
loading intersphinx inventory from https://docs.python.org/objects.inv...
loading intersphinx inventory from https://numpy.org/doc/stable/objects.inv...
loading intersphinx inventory from https://numcodecs.readthedocs.io/en/stable/objects.inv...
intersphinx inventory has moved: https://docs.python.org/objects.inv -> https://docs.python.org/3/objects.inv
[automodsumm] api/core.rst: found 1 automodsumm entries to generate
building [mo]: targets for 0 po files that are out of date
writing output...
building [man]: all manpages
updating environment: [new config] 24 added, 0 changed, 0 removed
reading sources... [100%] tutorial
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... zarr.1 { getting_started installation tutorial api api/creation api/core _autoapi/zarr.core.Array api/hierarchy api/storage api/n5 api/convenience api/codecs api/attrs api/sync api/v3 spec spec/v3 spec/v2 spec/v1 release license acknowledgments contributing } /home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/docs/tutorial.rst:289: WARNING: py:func reference target not found: zarr.group
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/docs/tutorial.rst:841: WARNING: py:class reference target not found: zarr.storage.MongoDB
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/creation.py:docstring of zarr.creation.create:1: WARNING: py:class reference target not found: numpy._typing._dtype_like._SupportsDType
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/creation.py:docstring of zarr.creation.create:1: WARNING: py:class reference target not found: numpy._typing._dtype_like._DTypeDict
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/creation.py:docstring of zarr.creation.create:1: WARNING: py:class reference target not found: zarr.sync.Synchronizer
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/creation.py:docstring of zarr.creation.create:1: WARNING: py:class reference target not found: zarr.types.MetaArray
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/core.py:docstring of zarr.core.Array.get_basic_selection:38: WARNING: py:obj reference target not found: __getitem__
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/core.py:docstring of zarr.core.Array.get_basic_selection:38: WARNING: py:obj reference target not found: __setitem__
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/core.py:docstring of zarr.core.Array.get_basic_selection:45: WARNING: py:func reference target not found: __getitem__
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/core.py:docstring of zarr.core.Array.get_block_selection:38: WARNING: py:obj reference target not found: __getitem__
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/core.py:docstring of zarr.core.Array.get_block_selection:38: WARNING: py:obj reference target not found: __setitem__
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/core.py:docstring of zarr.core.Array.get_coordinate_selection:38: WARNING: py:obj reference target not found: __getitem__
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/core.py:docstring of zarr.core.Array.get_coordinate_selection:38: WARNING: py:obj reference target not found: __setitem__
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/core.py:docstring of zarr.core.Array.get_mask_selection:40: WARNING: py:obj reference target not found: __getitem__
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/core.py:docstring of zarr.core.Array.get_mask_selection:40: WARNING: py:obj reference target not found: __setitem__
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/core.py:docstring of zarr.core.Array.get_orthogonal_selection:42: WARNING: py:obj reference target not found: __getitem__
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/core.py:docstring of zarr.core.Array.get_orthogonal_selection:42: WARNING: py:obj reference target not found: __setitem__
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/core.py:docstring of zarr.core.Array.set_basic_selection:34: WARNING: py:obj reference target not found: __getitem__
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/core.py:docstring of zarr.core.Array.set_basic_selection:34: WARNING: py:obj reference target not found: __setitem__
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/core.py:docstring of zarr.core.Array.set_basic_selection:39: WARNING: py:func reference target not found: __setitem__
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/core.py:docstring of zarr.core.Array.set_block_selection:34: WARNING: py:obj reference target not found: __getitem__
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/core.py:docstring of zarr.core.Array.set_block_selection:34: WARNING: py:obj reference target not found: __setitem__
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/core.py:docstring of zarr.core.Array.set_coordinate_selection:34: WARNING: py:obj reference target not found: __getitem__
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/core.py:docstring of zarr.core.Array.set_coordinate_selection:34: WARNING: py:obj reference target not found: __setitem__
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/core.py:docstring of zarr.core.Array.set_mask_selection:36: WARNING: py:obj reference target not found: __getitem__
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/core.py:docstring of zarr.core.Array.set_mask_selection:36: WARNING: py:obj reference target not found: __setitem__
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/core.py:docstring of zarr.core.Array.set_orthogonal_selection:34: WARNING: py:obj reference target not found: __getitem__
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/core.py:docstring of zarr.core.Array.set_orthogonal_selection:34: WARNING: py:obj reference target not found: __setitem__
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/hierarchy.py:docstring of zarr.hierarchy.Group:50: WARNING: py:obj reference target not found: store
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/hierarchy.py:docstring of zarr.hierarchy.Group:53: WARNING: py:obj reference target not found: path
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/hierarchy.py:docstring of zarr.hierarchy.Group:56: WARNING: py:obj reference target not found: name
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/hierarchy.py:docstring of zarr.hierarchy.Group:59: WARNING: py:obj reference target not found: read_only
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/hierarchy.py:docstring of zarr.hierarchy.Group:62: WARNING: py:obj reference target not found: chunk_store
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/hierarchy.py:docstring of zarr.hierarchy.Group:65: WARNING: py:obj reference target not found: synchronizer
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/hierarchy.py:docstring of zarr.hierarchy.Group:68: WARNING: py:obj reference target not found: attrs
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/hierarchy.py:docstring of zarr.hierarchy.Group:71: WARNING: py:obj reference target not found: info
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/hierarchy.py:docstring of zarr.hierarchy.Group:74: WARNING: py:obj reference target not found: meta_array
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/hierarchy.py:docstring of zarr.hierarchy.Group:113:<autosummary>:1: WARNING: py:obj reference target not found: zarr.hierarchy.Group.info
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/storage.py:docstring of zarr.storage.MemoryStore:2: WARNING: py:class reference target not found: KVStore
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/storage.py:docstring of zarr.storage.MemoryStore:29: WARNING: py:class reference target not found: KVStore
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/storage.py:docstring of zarr.storage.ZipStore:62: WARNING: py:func reference target not found: zarr.array
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/storage.py:docstring of zarr.storage.DBMStore:21: WARNING: py:func reference target not found: anydbm.open
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/storage.py:docstring of zarr.storage.LRUStoreCache:1: WARNING: py:class reference target not found: zarr._storage.store.BaseStore
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/storage.py:docstring of zarr.storage.ConsolidatedMetadataStore:1: WARNING: py:class reference target not found: zarr._storage.store.BaseStore
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/storage.py:docstring of zarr.storage.init_array:1: WARNING: py:class reference target not found: zarr._storage.store.BaseStore
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/storage.py:docstring of zarr.storage.init_array:1: WARNING: py:class reference target not found: zarr._storage.store.BaseStore
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/storage.py:docstring of zarr.storage.init_group:1: WARNING: py:class reference target not found: zarr._storage.store.BaseStore
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/storage.py:docstring of zarr.storage.init_group:1: WARNING: py:class reference target not found: zarr._storage.store.BaseStore
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/storage.py:docstring of zarr.storage.contains_array:1: WARNING: py:class reference target not found: zarr._storage.store.BaseStore
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/storage.py:docstring of zarr.storage.contains_group:1: WARNING: py:class reference target not found: zarr._storage.store.BaseStore
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/storage.py:docstring of zarr.storage.listdir:1: WARNING: py:class reference target not found: zarr._storage.store.BaseStore
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/storage.py:docstring of zarr.storage.rmdir:1: WARNING: py:class reference target not found: zarr._storage.store.BaseStore
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/storage.py:docstring of zarr.storage.getsize:1: WARNING: py:class reference target not found: zarr._storage.store.BaseStore
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/storage.py:docstring of zarr.storage.rename:1: WARNING: py:class reference target not found: zarr._storage.store.Store
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/convenience.py:docstring of zarr.convenience.open:1: WARNING: py:class reference target not found: zarr._storage.store.BaseStore
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/convenience.py:docstring of zarr.convenience.save:1: WARNING: py:class reference target not found: zarr._storage.store.BaseStore
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/convenience.py:docstring of zarr.convenience.save:45: WARNING: py:class reference target not found: DirectoryStore
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/convenience.py:docstring of zarr.convenience.save:54: WARNING: py:class reference target not found: ZipStore
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/convenience.py:docstring of zarr.convenience.save:60: WARNING: py:class reference target not found: DirectoryStore
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/convenience.py:docstring of zarr.convenience.save:87: WARNING: py:class reference target not found: ZipStore
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/convenience.py:docstring of zarr.convenience.load:1: WARNING: py:class reference target not found: zarr._storage.store.BaseStore
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/convenience.py:docstring of zarr.convenience.load:38: WARNING: py:obj reference target not found: savez
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/convenience.py:docstring of zarr.convenience.save_array:1: WARNING: py:class reference target not found: zarr._storage.store.BaseStore
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/convenience.py:docstring of zarr.convenience.save_array:27: WARNING: py:func reference target not found: create
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/convenience.py:docstring of zarr.convenience.save_array:41: WARNING: py:class reference target not found: DirectoryStore
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/convenience.py:docstring of zarr.convenience.save_array:50: WARNING: py:class reference target not found: ZipStore
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/convenience.py:docstring of zarr.convenience.save_group:1: WARNING: py:class reference target not found: zarr._storage.store.BaseStore
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/convenience.py:docstring of zarr.convenience.save_group:44: WARNING: py:class reference target not found: DirectoryStore
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/convenience.py:docstring of zarr.convenience.save_group:71: WARNING: py:class reference target not found: ZipStore
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/convenience.py:docstring of zarr.convenience.consolidate_metadata:1: WARNING: py:class reference target not found: zarr._storage.store.BaseStore
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/convenience.py:docstring of zarr.convenience.open_consolidated:1: WARNING: py:class reference target not found: zarr._storage.store.BaseStore
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/attrs.py:docstring of zarr.attrs.Attributes.keys:1: WARNING: py:class reference target not found: a set-like object providing a view on D's keys
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/_storage/v3.py:docstring of zarr._storage.v3.MemoryStoreV3:2: WARNING: py:class reference target not found: KVStore
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/_storage/v3.py:docstring of zarr._storage.v3.MemoryStoreV3:29: WARNING: py:class reference target not found: KVStore
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/_storage/v3.py:docstring of zarr._storage.v3.ZipStoreV3:62: WARNING: py:func reference target not found: zarr.array
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/_storage/v3.py:docstring of zarr._storage.v3.ZipStoreV3:66: WARNING: py:class reference target not found: DirectoryStore
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/_storage/v3.py:docstring of zarr._storage.v3.DBMStoreV3:21: WARNING: py:func reference target not found: anydbm.open
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/zarr/_storage/v3.py:docstring of zarr._storage.v3.ConsolidatedMetadataStoreV3:1: WARNING: py:class reference target not found: zarr._storage.store.BaseStore
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/docs/release.rst:1865: WARNING: py:func reference target not found: zarr.blosc.list_compressors
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/docs/release.rst:1865: WARNING: py:func reference target not found: zarr.blosc.get_nthreads
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/docs/release.rst:1900: WARNING: py:mod reference target not found: zarr.compressors
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/docs/release.rst:1922: WARNING: py:mod reference target not found: zarr.blosc
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/docs/release.rst:1929: WARNING: py:mod reference target not found: zarr.blosc
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/docs/release.rst:1933: WARNING: py:mod reference target not found: zarr.blosc
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/docs/contributing.rst:336: WARNING: py:func reference target not found: test_format_compatibility
/home/tkloczko/rpmbuild/BUILD/zarr-python-2.18.1/docs/contributing.rst:336: WARNING: py:mod reference target not found: zarr.tests.test_storage
done
build succeeded, 86 warnings.

Steps to reproduce

Run sphinx-build woith -n option.

Additional output

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

[dstansby]

Looking at the traceback, I think it's not unexpected that the package has to be installed before the docs can be built. So I think we can close this. Thanks for reporting though, and if I've got something wrong here feel free to re-open or comment!

[kloczek]

Warnings are NOT RELATED to is module installed or not.
Did you try to reproduce this issue adding -n option? 🤔

[dstansby]

Thanks - I opened a draft PR at #2424 to see what the errors look like now. Pull requests definitely welcome to fix the errors!