0.8.3: sphinx warnings `reference target not found`

[kloczek]

trafficstars

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 v6.2.1

Traceback (most recent call last):
  File "/usr/lib/python3.8/site-packages/sphinx/config.py", line 354, in eval_config_file
    exec(code, namespace)  # NoQA: S102
  File "/home/tkloczko/rpmbuild/BUILD/hatch-jupyter-builder-0.8.3/docs/conf.py", line 25, in <module>
    __version__ = package_version("hatch_jupyter_builder")
  File "/usr/lib64/python3.8/importlib/metadata.py", line 530, in version
    return distribution(distribution_name).version
  File "/usr/lib64/python3.8/importlib/metadata.py", line 503, in distribution
    return Distribution.from_name(distribution_name)
  File "/usr/lib64/python3.8/importlib/metadata.py", line 177, in from_name
    raise PackageNotFoundError(name)
importlib.metadata.PackageNotFoundError: hatch_jupyter_builder

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 280, in build_main
    app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
  File "/usr/lib/python3.8/site-packages/sphinx/application.py", line 207, in __init__
    self.config = Config.read(self.confdir, confoverrides or {}, self.tags)
  File "/usr/lib/python3.8/site-packages/sphinx/config.py", line 177, in read
    namespace = eval_config_file(filename, tags)
  File "/usr/lib/python3.8/site-packages/sphinx/config.py", line 367, 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 354, in eval_config_file
    exec(code, namespace)  # NoQA: S102
  File "/home/tkloczko/rpmbuild/BUILD/hatch-jupyter-builder-0.8.3/docs/conf.py", line 25, in <module>
    __version__ = package_version("hatch_jupyter_builder")
  File "/usr/lib64/python3.8/importlib/metadata.py", line 530, in version
    return distribution(distribution_name).version
  File "/usr/lib64/python3.8/importlib/metadata.py", line 503, in distribution
    return Distribution.from_name(distribution_name)
  File "/usr/lib64/python3.8/importlib/metadata.py", line 177, in from_name
    raise PackageNotFoundError(name)
importlib.metadata.PackageNotFoundError: hatch_jupyter_builder


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 354, in eval_config_file
    exec(code, namespace)  # NoQA: S102
  File "/home/tkloczko/rpmbuild/BUILD/hatch-jupyter-builder-0.8.3/docs/conf.py", line 25, in <module>
    __version__ = package_version("hatch_jupyter_builder")
  File "/usr/lib64/python3.8/importlib/metadata.py", line 530, in version
    return distribution(distribution_name).version
  File "/usr/lib64/python3.8/importlib/metadata.py", line 503, in distribution
    return Distribution.from_name(distribution_name)
  File "/usr/lib64/python3.8/importlib/metadata.py", line 177, in from_name
    raise PackageNotFoundError(name)
importlib.metadata.PackageNotFoundError: hatch_jupyter_builder

This can be fixed by patch like below:

--- a/docs/conf.py
+++ b/docs/conf.py
@@ -9,10 +9,11 @@
 # 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.
-#
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+
+import os
+import sys
+sys.path.insert(0, os.path.abspath(".."))
+
 from importlib.metadata import version as package_version

 # -- 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.

Here is the output with warnings:

+ /usr/bin/sphinx-build -n -T -b man docs build/sphinx/man
Running Sphinx v6.2.1
making output directory... done
myst v1.0.0: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions={'html_image'}, disable_syntax=[], all_links_external=False, url_schemes=('http', 'https', 'mailto', 'ftp'), ref_domains=None, fence_as_directive=set(), number_code_blocks=[], title_to_header=False, heading_anchors=0, heading_slug_func=None, html_meta={}, footnote_transition=True, words_per_minute=200, substitutions={}, linkify_fuzzy_links=True, dmath_allow_labels=True, dmath_allow_space=True, dmath_allow_digits=True, dmath_double_inline=False, update_mathjax=True, mathjax_classes='tex2jax_process|mathjax_process|math|output_area', enable_checkboxes=False, suppress_warnings=[], highlight_code_blocks=True)
building [mo]: targets for 0 po files that are out of date
writing output...
building [man]: all manpages
updating environment: [new config] 13 added, 0 changed, 0 removed
reading sources... [100%] source/reference/index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-hatch-jupyter-builder.3 { source/background/index source/get_started/index source/get_started/config source/how_to_guides/index source/how_to_guides/migrating_javascript_projects source/how_to_guides/migrating_data_files_projects source/reference/index source/reference/api/modules source/reference/api/hatch_jupyter_builder source/reference/api/hatch_jupyter_builder.compare_migrated source/reference/api/hatch_jupyter_builder.migrate source/reference/changelog } /home/tkloczko/rpmbuild/BUILD/hatch-jupyter-builder-0.8.3/hatch_jupyter_builder/compare_migrated/cli.py:docstring of hatch_jupyter_builder.compare_migrated.cli.make_parser:4: WARNING: py:class reference target not found: argparse.ArgumentParser
/home/tkloczko/rpmbuild/BUILD/hatch-jupyter-builder-0.8.3/hatch_jupyter_builder/migrate/cli.py:docstring of hatch_jupyter_builder.migrate.cli.make_parser:4: WARNING: py:class reference target not found: argparse.ArgumentParser
/home/tkloczko/rpmbuild/BUILD/hatch-jupyter-builder-0.8.3/hatch_jupyter_builder/cli.py:docstring of hatch_jupyter_builder.cli.make_parser:4: WARNING: py:class reference target not found: argparse.ArgumentParser
<unknown>:1: WARNING: py:data reference target not found: typing.Optional
/home/tkloczko/rpmbuild/BUILD/hatch-jupyter-builder-0.8.3/hatch_jupyter_builder/plugin.py:docstring of hatch_jupyter_builder.plugin.JupyterBuildHook:1: WARNING: py:class reference target not found: hatchling.builders.hooks.plugin.interface.BuildHookInterface
/home/tkloczko/rpmbuild/BUILD/hatch-jupyter-builder-0.8.3/hatch_jupyter_builder/utils.py:docstring of hatch_jupyter_builder.utils.get_build_func:4: WARNING: py:data reference target not found: typing.Callable
/home/tkloczko/rpmbuild/BUILD/hatch-jupyter-builder-0.8.3/hatch_jupyter_builder/utils.py:docstring of hatch_jupyter_builder.utils.get_build_func:4: WARNING: py:data reference target not found: Ellipsis
/home/tkloczko/rpmbuild/BUILD/hatch-jupyter-builder-0.8.3/hatch_jupyter_builder/utils.py:docstring of hatch_jupyter_builder.utils.normalize_kwargs:4: WARNING: py:data reference target not found: typing.Any
/home/tkloczko/rpmbuild/BUILD/hatch-jupyter-builder-0.8.3/hatch_jupyter_builder/utils.py:docstring of hatch_jupyter_builder.utils.npm_builder:1: WARNING: py:class reference target not found: optional
/home/tkloczko/rpmbuild/BUILD/hatch-jupyter-builder-0.8.3/hatch_jupyter_builder/utils.py:docstring of hatch_jupyter_builder.utils.npm_builder:1: WARNING: py:class reference target not found: optional
/home/tkloczko/rpmbuild/BUILD/hatch-jupyter-builder-0.8.3/hatch_jupyter_builder/utils.py:docstring of hatch_jupyter_builder.utils.npm_builder:1: WARNING: py:class reference target not found: optional
/home/tkloczko/rpmbuild/BUILD/hatch-jupyter-builder-0.8.3/hatch_jupyter_builder/utils.py:docstring of hatch_jupyter_builder.utils.npm_builder:1: WARNING: py:class reference target not found: optional
/home/tkloczko/rpmbuild/BUILD/hatch-jupyter-builder-0.8.3/hatch_jupyter_builder/utils.py:docstring of hatch_jupyter_builder.utils.npm_builder:1: WARNING: py:class reference target not found: optional.
/home/tkloczko/rpmbuild/BUILD/hatch-jupyter-builder-0.8.3/hatch_jupyter_builder/utils.py:docstring of hatch_jupyter_builder.utils.npm_builder:1: WARNING: py:class reference target not found: optional.
done
build succeeded, 14 warnings.

You can peak on fixes that kind of issues in other projects https://github.com/RDFLib/rdflib-sqlalchemy/issues/95 https://github.com/RDFLib/rdflib/pull/2036 https://github.com/click-contrib/sphinx-click/commit/abc31069 https://github.com/frostming/unearth/issues/14 https://github.com/jaraco/cssutils/issues/21 https://github.com/latchset/jwcrypto/pull/289 https://github.com/latchset/jwcrypto/pull/289 https://github.com/pypa/distlib/commit/98b9b89f https://github.com/pywbem/pywbem/pull/2895 https://github.com/sissaschool/elementpath/commit/bf869d9e https://github.com/sissaschool/xmlschema/commit/42ea98f2 https://github.com/sqlalchemy/sqlalchemy/commit/5e88e6e8

[welcome[bot]]

Thank you for opening your first issue in this project! Engagement like this is essential for open source projects! :hugs:
If you haven't done so already, check out Jupyter's Code of Conduct. Also, please try to follow the issue template as it helps other other community members to contribute more effectively. You can meet the other Jovyans by joining our Discourse forum. There is also an intro thread there where you can stop by and say Hi! :wave:
Welcome to the Jupyter community! :tada: