5.4.0: sphinx 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 docs build/sphinx/man
Running Sphinx v5.0.1
WARNING: Invalid configuration value found: 'language = None'. Update your configuration to a valid langauge code. Falling back to 'en' (English).
making output directory... done
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
loading intersphinx inventory from https://jupyter-client.readthedocs.io/en/stable/objects.inv...
loading intersphinx inventory from https://nbconvert.readthedocs.org/en/stable/objects.inv...
loading intersphinx inventory from https://jupyter-notebook.readthedocs.org/en/stable/objects.inv...
intersphinx inventory has moved: https://jupyter-notebook.readthedocs.org/en/stable/objects.inv -> https://jupyter-notebook.readthedocs.io/en/stable/objects.inv
intersphinx inventory has moved: https://nbconvert.readthedocs.org/en/stable/objects.inv -> https://nbconvert.readthedocs.io/en/stable/objects.inv
building [mo]: targets for 0 po files that are out of date
building [man]: all manpages
updating environment: [new config] 5 added, 0 changed, 0 removed
reading sources... [100%] markup
WARNING: autodoc: failed to import function 'read' from module 'nbformat'; the following exception was raised:
No module named 'nbformat'
WARNING: autodoc: failed to import function 'reads' from module 'nbformat'; the following exception was raised:
No module named 'nbformat'
WARNING: autodoc: failed to import function 'write' from module 'nbformat'; the following exception was raised:
No module named 'nbformat'
WARNING: autodoc: failed to import function 'writes' from module 'nbformat'; the following exception was raised:
No module named 'nbformat'
WARNING: autodoc: failed to import class 'NotebookNode' from module 'nbformat'; the following exception was raised:
No module named 'nbformat'
WARNING: autodoc: failed to import function 'from_dict' from module 'nbformat'; the following exception was raised:
No module named 'nbformat'
WARNING: autodoc: failed to import function 'convert' from module 'nbformat'; the following exception was raised:
No module named 'nbformat'
WARNING: autodoc: failed to import function 'validate' from module 'nbformat'; the following exception was raised:
No module named 'nbformat'
WARNING: autodoc: failed to import class 'ValidationError' from module 'nbformat'; the following exception was raised:
No module named 'nbformat'
WARNING: autodoc: failed to import function 'v4.new_notebook' from module 'nbformat'; the following exception was raised:
No module named 'nbformat'
WARNING: autodoc: failed to import function 'v4.new_code_cell' from module 'nbformat'; the following exception was raised:
No module named 'nbformat'
WARNING: autodoc: failed to import function 'v4.new_markdown_cell' from module 'nbformat'; the following exception was raised:
No module named 'nbformat'
WARNING: autodoc: failed to import function 'v4.new_raw_cell' from module 'nbformat'; the following exception was raised:
No module named 'nbformat'
WARNING: autodoc: failed to import function 'v4.new_output' from module 'nbformat'; the following exception was raised:
No module named 'nbformat'
WARNING: autodoc: failed to import function 'v4.output_from_msg' from module 'nbformat'; the following exception was raised:
No module named 'nbformat'
WARNING: autodoc: failed to import class 'sign.NotebookNotary' from module 'nbformat'; the following exception was raised:
No module named 'nbformat'
WARNING: autodoc: failed to import class 'sign.SignatureStore' from module 'nbformat'; the following exception was raised:
No module named 'nbformat'
WARNING: autodoc: failed to import class 'sign.SQLiteSignatureStore' from module 'nbformat'; the following exception was raised:
No module named 'nbformat'
WARNING: autodoc: failed to import class 'sign.MemorySignatureStore' from module 'nbformat'; the following exception was raised:
No module named 'nbformat'
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-nbformat.3 { format_description markup api changelog } /home/tkloczko/rpmbuild/BUILD/nbformat-5.4.0/docs/api.rst:40: WARNING: py:class reference target not found: NotebookNode
/home/tkloczko/rpmbuild/BUILD/nbformat-5.4.0/docs/api.rst:62: WARNING: py:class reference target not found: NotebookNode
/home/tkloczko/rpmbuild/BUILD/nbformat-5.4.0/docs/api.rst:103: WARNING: py:class reference target not found: SignatureStore
/home/tkloczko/rpmbuild/BUILD/nbformat-5.4.0/docs/api.rst:117: WARNING: py:class reference target not found: NotebookNotary
/home/tkloczko/rpmbuild/BUILD/nbformat-5.4.0/docs/changelog.rst:135: WARNING: py:func reference target not found: nbformat.validate
/home/tkloczko/rpmbuild/BUILD/nbformat-5.4.0/docs/changelog.rst:150: WARNING: py:func reference target not found: nbformat.read
/home/tkloczko/rpmbuild/BUILD/nbformat-5.4.0/docs/changelog.rst:150: WARNING: py:func reference target not found: nbformat.write
/home/tkloczko/rpmbuild/BUILD/nbformat-5.4.0/docs/changelog.rst:152: WARNING: py:func reference target not found: nbformat.validate
done
build succeeded, 28 warnings.

First part of those fixes can be fixed by patch like below:

--- a/docs/conf.py~     2022-05-05 00:03:27.000000000 +0000
+++ b/docs/conf.py      2022-05-05 00:04:32.758233565 +0000
@@ -15,7 +15,9 @@
 # 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.insert(0, os.path.abspath('.'))
+import os
+import sys
+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

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.

Summary warnings with that patch:

+ /usr/bin/sphinx-build -n -T -b man docs build/sphinx/man
Running Sphinx v5.0.1
WARNING: Invalid configuration value found: 'language = None'. Update your configuration to a valid langauge code. Falling back to 'en' (English).
making output directory... done
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
loading intersphinx inventory from https://jupyter-client.readthedocs.io/en/stable/objects.inv...
loading intersphinx inventory from https://nbconvert.readthedocs.org/en/stable/objects.inv...
loading intersphinx inventory from https://jupyter-notebook.readthedocs.org/en/stable/objects.inv...
intersphinx inventory has moved: https://nbconvert.readthedocs.org/en/stable/objects.inv -> https://nbconvert.readthedocs.io/en/stable/objects.inv
intersphinx inventory has moved: https://jupyter-notebook.readthedocs.org/en/stable/objects.inv -> https://jupyter-notebook.readthedocs.io/en/stable/objects.inv
building [mo]: targets for 0 po files that are out of date
building [man]: all manpages
updating environment: [new config] 5 added, 0 changed, 0 removed
reading sources... [100%] markup
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-nbformat.3 { format_description markup api changelog } /home/tkloczko/rpmbuild/BUILD/nbformat-5.4.0/nbformat/__init__.py:docstring of nbformat.read:: WARNING: py:class reference target not found: file
/home/tkloczko/rpmbuild/BUILD/nbformat-5.4.0/nbformat/__init__.py:docstring of nbformat.read:: WARNING: py:class reference target not found: optional
/home/tkloczko/rpmbuild/BUILD/nbformat-5.4.0/nbformat/__init__.py:docstring of nbformat.reads:: WARNING: py:class reference target not found: unicode
/home/tkloczko/rpmbuild/BUILD/nbformat-5.4.0/nbformat/__init__.py:docstring of nbformat.reads:: WARNING: py:class reference target not found: optional
/home/tkloczko/rpmbuild/BUILD/nbformat-5.4.0/nbformat/__init__.py:docstring of nbformat.write:: WARNING: py:class reference target not found: file
/home/tkloczko/rpmbuild/BUILD/nbformat-5.4.0/nbformat/__init__.py:docstring of nbformat.write:: WARNING: py:class reference target not found: optional
/home/tkloczko/rpmbuild/BUILD/nbformat-5.4.0/nbformat/__init__.py:docstring of nbformat.write:: WARNING: py:class reference target not found: optional
/home/tkloczko/rpmbuild/BUILD/nbformat-5.4.0/nbformat/__init__.py:docstring of nbformat.writes:: WARNING: py:class reference target not found: optional
/home/tkloczko/rpmbuild/BUILD/nbformat-5.4.0/nbformat/__init__.py:docstring of nbformat.writes:: WARNING: py:class reference target not found: optional
/home/tkloczko/rpmbuild/BUILD/nbformat-5.4.0/nbformat/__init__.py:docstring of nbformat.writes:: WARNING: py:class reference target not found: unicode
/home/tkloczko/rpmbuild/BUILD/nbformat-5.4.0/nbformat/v4/nbbase.py:docstring of nbformat.v4.nbbase.output_from_msg:: WARNING: py:class reference target not found: the output as a notebook node.
done
build succeeded, 12 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