0.18.1: sphinx warnings `reference target not found`

[kloczek]

First of all currently on 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
making output directory... done
myst v3.0.1: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions=set(), disable_syntax=[], all_links_external=False, links_external_new_tab=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)
loading intersphinx inventory from http://www.tornadoweb.org/en/stable/objects.inv...
intersphinx inventory has moved: http://www.tornadoweb.org/en/stable/objects.inv -> https://www.tornadoweb.org/en/stable/objects.inv
building [mo]: targets for 0 po files that are out of date
writing output...
building [man]: all manpages
updating environment: [new config] 4 added, 0 changed, 0 removed
reading sources... [100%] websocket
WARNING: autodoc: failed to import class 'SingleTermManager' from module 'terminado'; the following exception was raised:
No module named 'terminado'
WARNING: autodoc: failed to import class 'UniqueTermManager' from module 'terminado'; the following exception was raised:
No module named 'terminado'
WARNING: autodoc: failed to import class 'NamedTermManager' from module 'terminado'; the following exception was raised:
No module named 'terminado'
WARNING: autodoc: failed to import class 'TermManagerBase' from module 'terminado'; the following exception was raised:
No module named 'terminado'
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-terminado.3 { websocket uimodule changelog } /home/tkloczko/rpmbuild/BUILD/terminado-0.18.1/doc/websocket.rst:4: WARNING: py:class reference target not found: terminado.TermSocket
/home/tkloczko/rpmbuild/BUILD/terminado-0.18.1/doc/websocket.rst:4: WARNING: py:class reference target not found: tornado.web.WebSocketHandler
/home/tkloczko/rpmbuild/BUILD/terminado-0.18.1/doc/websocket.rst:24: WARNING: py:class reference target not found: terminado.TermSocket
/home/tkloczko/rpmbuild/BUILD/terminado-0.18.1/doc/uimodule.rst:25: WARNING: py:class reference target not found: terminado.uimodule.Terminal
/home/tkloczko/rpmbuild/BUILD/terminado-0.18.1/doc/uimodule.rst:25: WARNING: py:meth reference target not found: terminado.uimodule.Terminal.javascript_files
done
build succeeded, 9 warnings.

This can be fixed by patch like below: ```patch --- a/doc/conf.py +++ b/doc/conf.py @@ -11,6 +11,7 @@ # All configuration values have a default; values that are commented out # serve to show the default.

+import os
import shutil
import sys
from pathlib import Path
@@ -21,7 +22,7 @@

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 osp.abspath to make it absolute, like shown here.

-# sys.path.insert(0, osp.abspath('.'))
+sys.path.insert(0, os.path.abspath(".."))

-- General configuration ------------------------------------------------

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 above 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:
<details>

```console
+ /usr/bin/sphinx-build -n -T -b man doc build/sphinx/man
Running Sphinx v7.3.7
making output directory... done
myst v3.0.1: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions=set(), disable_syntax=[], all_links_external=False, links_external_new_tab=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)
loading intersphinx inventory from http://www.tornadoweb.org/en/stable/objects.inv...
intersphinx inventory has moved: http://www.tornadoweb.org/en/stable/objects.inv -> https://www.tornadoweb.org/en/stable/objects.inv
building [mo]: targets for 0 po files that are out of date
writing output...
building [man]: all manpages
updating environment: [new config] 4 added, 0 changed, 0 removed
reading sources... [100%] websocket
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-terminado.3 { websocket uimodule changelog } /home/tkloczko/rpmbuild/BUILD/terminado-0.18.1/doc/websocket.rst:4: WARNING: py:class reference target not found: terminado.TermSocket
/home/tkloczko/rpmbuild/BUILD/terminado-0.18.1/doc/websocket.rst:4: WARNING: py:class reference target not found: tornado.web.WebSocketHandler
/home/tkloczko/rpmbuild/BUILD/terminado-0.18.1/doc/websocket.rst:24: WARNING: py:class reference target not found: terminado.TermSocket
/home/tkloczko/rpmbuild/BUILD/terminado-0.18.1/terminado/management.py:docstring of terminado.management.TermManagerBase.get_terminal:1: WARNING: py:class reference target not found: terminado.management.PtyWithClients
/home/tkloczko/rpmbuild/BUILD/terminado-0.18.1/terminado/management.py:docstring of terminado.management.TermManagerBase.get_terminal:3: WARNING: py:class reference target not found: TermSocket
/home/tkloczko/rpmbuild/BUILD/terminado-0.18.1/terminado/management.py:docstring of terminado.management.TermManagerBase.new_terminal:1: WARNING: py:class reference target not found: terminado.management.PtyWithClients
/home/tkloczko/rpmbuild/BUILD/terminado-0.18.1/terminado/management.py:docstring of terminado.management.TermManagerBase.new_terminal:1: WARNING: py:class reference target not found: PtyWithClients
/home/tkloczko/rpmbuild/BUILD/terminado-0.18.1/terminado/management.py:docstring of terminado.management.TermManagerBase.start_reading:1: WARNING: py:class reference target not found: terminado.management.PtyWithClients
/home/tkloczko/rpmbuild/BUILD/terminado-0.18.1/doc/uimodule.rst:25: WARNING: py:class reference target not found: terminado.uimodule.Terminal
/home/tkloczko/rpmbuild/BUILD/terminado-0.18.1/doc/uimodule.rst:25: WARNING: py:meth reference target not found: terminado.uimodule.Terminal.javascript_files
done
build succeeded, 10 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