0.5.1: sphinx warnings reference target not found

[kloczek]

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

+ /usr/bin/sphinx-build -n -T -b man docs build/sphinx/man
Running Sphinx v5.0.2
making output directory... done
WARNING: html_static_path entry '_static' does not exist
myst v0.17.2: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions=[], 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', disable_syntax=[], all_links_external=False, url_schemes=('http', 'https', 'mailto', 'ftp'), ref_domains=None, highlight_code_blocks=True, number_code_blocks=[], title_to_header=False, heading_anchors=None, heading_slug_func=None, footnote_transition=True, sub_delimiters=('{', '}'), words_per_minute=200)
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%] requirements
WARNING: autodoc: failed to import module 'evaluator' from module 'unearth'; the following exception was raised:
No module named 'unearth'
WARNING: autodoc: failed to import class 'evaluator.Evaluator' from module 'unearth'; the following exception was raised:
No module named 'unearth'
WARNING: autodoc: failed to import class 'evaluator.Package' from module 'unearth'; the following exception was raised:
No module named 'unearth'
WARNING: autodoc: failed to import class 'evaluator.TargetPython' from module 'unearth'; the following exception was raised:
No module named 'unearth'
WARNING: autodoc: failed to import function 'evaluator.evaluate_package' from module 'unearth'; the following exception was raised:
No module named 'unearth'
WARNING: autodoc: failed to import module 'finder' from module 'unearth'; the following exception was raised:
No module named 'unearth'
WARNING: autodoc: failed to import class 'finder.PackageFinder' from module 'unearth'; the following exception was raised:
No module named 'unearth'
WARNING: autodoc: failed to import class 'finder.BestMatch' from module 'unearth'; the following exception was raised:
No module named 'unearth'
WARNING: autodoc: failed to import module 'link' from module 'unearth'; the following exception was raised:
No module named 'unearth'
WARNING: autodoc: failed to import class 'link.Link' from module 'unearth'; the following exception was raised:
No module named 'unearth'
/home/tkloczko/rpmbuild/BUILD/unearth-0.5.1/docs/cli_reference.md:4: ERROR: Failed to import "cli_parser" from "unearth.__main__".
No module named 'unearth'
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-Unearth.3 { requirements api/evaluator api/finder api/link cli_reference contributing } done
build succeeded, 12 warnings.

This can be fixed by patch like below:

--- a/docs/conf.py
+++ b/docs/conf.py
@@ -10,9 +10,9 @@
 # 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("../src"))


 # -- 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 docs build/sphinx/man
Running Sphinx v5.0.2
making output directory... done
WARNING: html_static_path entry '_static' does not exist
myst v0.17.2: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions=[], 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', disable_syntax=[], all_links_external=False, url_schemes=('http', 'https', 'mailto', 'ftp'), ref_domains=None, highlight_code_blocks=True, number_code_blocks=[], title_to_header=False, heading_anchors=None, heading_slug_func=None, footnote_transition=True, sub_delimiters=('{', '}'), words_per_minute=200)
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%] requirements
/home/tkloczko/rpmbuild/BUILD/unearth-0.5.1/src/unearth/finder.py:docstring of unearth.finder.BestMatch.applicable:1: WARNING: duplicate object description of unearth.finder.BestMatch.applicable, other instance in api/finder, use :noindex: for one of them
/home/tkloczko/rpmbuild/BUILD/unearth-0.5.1/src/unearth/finder.py:docstring of unearth.finder.BestMatch.best:1: WARNING: duplicate object description of unearth.finder.BestMatch.best, other instance in api/finder, use :noindex: for one of them
/home/tkloczko/rpmbuild/BUILD/unearth-0.5.1/src/unearth/finder.py:docstring of unearth.finder.BestMatch.candidates:1: WARNING: duplicate object description of unearth.finder.BestMatch.candidates, other instance in api/finder, use :noindex: for one of them
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-Unearth.3 { requirements api/evaluator api/finder api/link cli_reference contributing } /home/tkloczko/rpmbuild/BUILD/unearth-0.5.1/src/unearth/evaluator.py:docstring of unearth.evaluator.evaluate_package:: WARNING: py:class reference target not found: Requirement
/home/tkloczko/rpmbuild/BUILD/unearth-0.5.1/src/unearth/evaluator.py:docstring of unearth.evaluator.evaluate_package:: WARNING: py:class reference target not found: Requirement
/home/tkloczko/rpmbuild/BUILD/unearth-0.5.1/src/unearth/finder.py:docstring of unearth.finder.PackageFinder:: WARNING: py:class reference target not found: PyPISession
/home/tkloczko/rpmbuild/BUILD/unearth-0.5.1/src/unearth/finder.py:docstring of unearth.finder.PackageFinder:: WARNING: py:class reference target not found: PyPISession
/home/tkloczko/rpmbuild/BUILD/unearth-0.5.1/src/unearth/finder.py:docstring of unearth.finder.PackageFinder.download_and_unpack:: WARNING: py:class reference target not found: Path
/home/tkloczko/rpmbuild/BUILD/unearth-0.5.1/src/unearth/finder.py:docstring of unearth.finder.PackageFinder.download_and_unpack:: WARNING: py:class reference target not found: Path
/home/tkloczko/rpmbuild/BUILD/unearth-0.5.1/src/unearth/finder.py:docstring of unearth.finder.PackageFinder.download_and_unpack:: WARNING: py:class reference target not found: Path
/home/tkloczko/rpmbuild/BUILD/unearth-0.5.1/src/unearth/finder.py:docstring of unearth.finder.PackageFinder.download_and_unpack:: WARNING: py:class reference target not found: Path
/home/tkloczko/rpmbuild/BUILD/unearth-0.5.1/src/unearth/finder.py:docstring of unearth.finder.PackageFinder.download_and_unpack:: WARNING: py:class reference target not found: Path
/home/tkloczko/rpmbuild/BUILD/unearth-0.5.1/src/unearth/finder.py:docstring of unearth.finder.PackageFinder.download_and_unpack:: WARNING: py:class reference target not found: Path
/home/tkloczko/rpmbuild/BUILD/unearth-0.5.1/src/unearth/finder.py:docstring of unearth.finder.PackageFinder.find_best_match:: WARNING: py:class reference target not found: Requirement
/home/tkloczko/rpmbuild/BUILD/unearth-0.5.1/src/unearth/finder.py:docstring of unearth.finder.PackageFinder.find_best_match:: WARNING: py:class reference target not found: Requirement
/home/tkloczko/rpmbuild/BUILD/unearth-0.5.1/src/unearth/finder.py:docstring of unearth.finder.PackageFinder.find_matches:: WARNING: py:class reference target not found: Requirement
/home/tkloczko/rpmbuild/BUILD/unearth-0.5.1/src/unearth/finder.py:docstring of unearth.finder.PackageFinder.find_matches:: WARNING: py:class reference target not found: Requirement
/home/tkloczko/rpmbuild/BUILD/unearth-0.5.1/src/unearth/link.py:docstring of unearth.link.Link.from_path:: WARNING: py:class reference target not found: Path
done
build succeeded, 19 warnings.

You can peak on fixes that kind of issues in other projects
latchset/jwcrypto#289
click-contrib/sphinx-click@abc31069
latchset/jwcrypto#289
RDFLib/rdflib-sqlalchemy#95
sissaschool/elementpath@bf869d9e
jaraco/cssutils#21
pywbem/pywbem#2895

[frostming]

Did you install docs/requirements.txt before running sphinx command?

[kloczek]

I have installed in build all requirements and those warnings have nothing to do with requirements.
On log there is nothing about missing modules.
Please try what I've described.

[frostming]

I can't make it succeed even with your solution. A lot of errors like target reference not found: Path. It seems to me that -n is a too strict option. The current doc is enough.

[frostming]

Honestly, the issues you raised confused me because it seems you are using some build techniques I am not used to and blame the project for some errors that would never happen if I do not use the techniques you use. For example. sys.path.insert('../src') doesn't make sense to me because I always build docs from the project root, that path should be ./src. Even so, it only exposes the packages in sys.path, which should be already done by pip install -r docs/requirements.txt(it has a line of . -- installing this project itself).

[kloczek]

For example. sys.path.insert('../src') doesn't make sense to me because I always build docs from the project root, that path should be ./src.

Of course it make sense.
sphinx-buid command on its start changes current directory to the directory where is conf.py file.
Did you had a look on https://www.sphinx-doc.org/en/master/usage/configuration.html#example-of-configuration-file?

Without fixed refferences for example any API names mentioned in html or qch documentation format will be only hinglighted. When those warnings will be fixed you will have liks to exact symbols descriptions.
I'm interested only roff output (man page) and in this case thiose refferences are not used.
If you don't care about presence of those links that is perfectly fine.

[frostming]

Do you know how can I configure sphinx to make -n happy? I already tried intersphinx but it still complains target not found :Requirement

[kloczek]

There is no such thing in this case like "sphinx configutation".
Look on links to the tickets/PRs/commitch which I've dropped.

[frostming]

Yeah I have looked at them, they are similar and all leave some reference not found warning unresolved in the end.

What do you want from my side to fix it? Ignore the warnings? The sys.path.insert doesn't do the trick

[kloczek]

My advice is "do what you want".
I'm only a messanger ..

Altering sys.path is to allow AT ALL sphinx-build command process files when it is used directly to generate documentation out of source tree without have unearth module installed.
This patch has nothing to do with those warnings.

[frostming]

Fixed in the main branch

[kloczek]

Testeda and now it looks clean 👍 😄

+ /usr/bin/sphinx-build -n -T -b man docs build/sphinx/man
Running Sphinx v5.0.2
making output directory... done
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
loading intersphinx inventory from https://packaging.pypa.io/en/latest/objects.inv...
loading intersphinx inventory from https://requests.readthedocs.io/en/latest/objects.inv...
myst v0.17.2: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions=[], 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', disable_syntax=[], all_links_external=False, url_schemes=('http', 'https', 'mailto', 'ftp'), ref_domains=None, highlight_code_blocks=True, number_code_blocks=[], title_to_header=False, heading_anchors=None, heading_slug_func=None, footnote_transition=True, sub_delimiters=('{', '}'), words_per_minute=200)
building [mo]: targets for 0 po files that are out of date
building [man]: all manpages
updating environment: [new config] 8 added, 0 changed, 0 removed
reading sources... [100%] requirements
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-Unearth.3 { requirements api/evaluator api/finder api/link api/session cli_reference contributing } done
build succeeded.

Thank you 😃