1.0.4: 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

Details

+ /usr/bin/sphinx-build -n -T -b man docs build/sphinx/man
Running Sphinx v5.0.1
making output directory... done
WARNING: html_static_path entry '_static' does not exist
building [mo]: targets for 0 po files that are out of date
building [man]: all manpages
updating environment: [new config] 3 added, 0 changed, 0 removed
reading sources... [100%] index
WARNING: autodoc: failed to import function 'pack' from module 'msgpack'; the following exception was raised:
No module named 'msgpack'
WARNING: autodoc: failed to import function 'packb' from module 'msgpack'; the following exception was raised:
No module named 'msgpack'
WARNING: autodoc: failed to import function 'unpack' from module 'msgpack'; the following exception was raised:
No module named 'msgpack'
WARNING: autodoc: failed to import function 'unpackb' from module 'msgpack'; the following exception was raised:
No module named 'msgpack'
WARNING: autodoc: failed to import class 'Packer' from module 'msgpack'; the following exception was raised:
No module named 'msgpack'
WARNING: autodoc: failed to import class 'Unpacker' from module 'msgpack'; the following exception was raised:
No module named 'msgpack'
WARNING: autodoc: failed to import class 'ExtType' from module 'msgpack'; the following exception was raised:
No module named 'msgpack'
WARNING: autodoc: failed to import class 'Timestamp' from module 'msgpack'; the following exception was raised:
No module named 'msgpack'
WARNING: autodoc: failed to import module 'exceptions' from module 'msgpack'; the following exception was raised:
No module named 'msgpack'
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-msgpack.3 { api advanced } /home/tkloczko/rpmbuild/BUILD/msgpack-python-1.0.4/docs/api.rst:8: WARNING: py:func reference target not found: dump
/home/tkloczko/rpmbuild/BUILD/msgpack-python-1.0.4/docs/api.rst:8: WARNING: py:func reference target not found: pack
/home/tkloczko/rpmbuild/BUILD/msgpack-python-1.0.4/docs/api.rst:12: WARNING: py:func reference target not found: dumps
/home/tkloczko/rpmbuild/BUILD/msgpack-python-1.0.4/docs/api.rst:12: WARNING: py:func reference target not found: packb
/home/tkloczko/rpmbuild/BUILD/msgpack-python-1.0.4/docs/api.rst:16: WARNING: py:func reference target not found: load
/home/tkloczko/rpmbuild/BUILD/msgpack-python-1.0.4/docs/api.rst:16: WARNING: py:func reference target not found: unpack
/home/tkloczko/rpmbuild/BUILD/msgpack-python-1.0.4/docs/api.rst:20: WARNING: py:func reference target not found: loads
/home/tkloczko/rpmbuild/BUILD/msgpack-python-1.0.4/docs/api.rst:20: WARNING: py:func reference target not found: unpackb
/home/tkloczko/rpmbuild/BUILD/msgpack-python-1.0.4/docs/advanced.rst:10: WARNING: py:class reference target not found: msgpack.Packer
/home/tkloczko/rpmbuild/BUILD/msgpack-python-1.0.4/docs/advanced.rst:13: WARNING: py:meth reference target not found: msgpack.Packer.bytes
/home/tkloczko/rpmbuild/BUILD/msgpack-python-1.0.4/docs/advanced.rst:13: WARNING: py:meth reference target not found: msgpack.Packer.getbuffer
done
build succeeded, 21 warnings.

First part of warnings can be fixed by patch like below:

--- a/docs/conf.py~     2022-06-05 08:01:50.000000000 +0000
+++ b/docs/conf.py      2022-06-05 08:02:43.878255796 +0000
@@ -16,7 +16,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 os.path.abspath to make it absolute, like shown here.
-# sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath(".."))

 # -- General configuration -----------------------------------------------------
 author = "Inada Naoki"

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.

Details

+ /usr/bin/sphinx-build -n -T -b man docs build/sphinx/man
Running Sphinx v5.0.1
making output directory... done
WARNING: html_static_path entry '_static' does not exist
building [mo]: targets for 0 po files that are out of date
building [man]: all manpages
updating environment: [new config] 3 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-msgpack.3 { api advanced } /home/tkloczko/rpmbuild/BUILD/msgpack-python-1.0.4/docs/api.rst:8: WARNING: py:func reference target not found: dump
/home/tkloczko/rpmbuild/BUILD/msgpack-python-1.0.4/docs/api.rst:12: WARNING: py:func reference target not found: dumps
/home/tkloczko/rpmbuild/BUILD/msgpack-python-1.0.4/docs/api.rst:16: WARNING: py:func reference target not found: load
/home/tkloczko/rpmbuild/BUILD/msgpack-python-1.0.4/docs/api.rst:20: WARNING: py:func reference target not found: loads
/home/tkloczko/rpmbuild/BUILD/msgpack-python-1.0.4/msgpack/fallback.py:docstring of msgpack.fallback.Packer:: WARNING: py:class reference target not found: callable
/home/tkloczko/rpmbuild/BUILD/msgpack-python-1.0.4/msgpack/fallback.py:docstring of msgpack.fallback.Unpacker:6: WARNING: py:meth reference target not found: feed
/home/tkloczko/rpmbuild/BUILD/msgpack-python-1.0.4/msgpack/fallback.py:docstring of msgpack.fallback.Unpacker:: WARNING: py:class reference target not found: callable
/home/tkloczko/rpmbuild/BUILD/msgpack-python-1.0.4/msgpack/fallback.py:docstring of msgpack.fallback.Unpacker:: WARNING: py:class reference target not found: callable
/home/tkloczko/rpmbuild/BUILD/msgpack-python-1.0.4/msgpack/ext.py:docstring of msgpack.ext.Timestamp.from_unix:: WARNING: py:class reference target not found: float.
/home/tkloczko/rpmbuild/BUILD/msgpack-python-1.0.4/msgpack/ext.py:docstring of msgpack.ext.Timestamp.to_datetime:: WARNING: py:class reference target not found: datetime.
done
build succeeded, 11 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

[ThomasWaldmann]

@kloczek can you review #554 please?

[kloczek]

One sec 😋

[kloczek]

ERROR Missing dependencies:
        Cython~=3.0.0

Cannot temporary test this PR because I'm holding upgrade of the cython to 3.x as there are few issues with that upgrade which affects builds of some modules.
Hopefully those issues will be sorted out shortly.
Will back when will upgrade my packages to cython to 3.x.

[kloczek]

Tested that and all look clean now 👍 😄

+ /usr/bin/sphinx-build -n -T -b man docs build/sphinx/man
Running Sphinx v7.0.1
making output directory... done
building [mo]: targets for 0 po files that are out of date
writing output...
building [man]: all manpages
updating environment: [new config] 3 added, 0 changed, 0 removed
reading sources... [ 33%] advanced
reading sources... [ 66%] api
reading sources... [100%] index

looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-msgpack.3 { api advanced } done
build succeeded.

[kloczek]

I've added #556 with some minor conf.py cleanups 😋