0.17.0: sphinx warnings `reference target not found`

[kloczek]

Fisrst of all: it ins not possible use straight sphinx to build cleanly documentation out of source tree.

+ /usr/bin/sphinx-build -n -T -b man docs build/sphinx/man
Running Sphinx v4.5.0
making output directory... done
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
building [mo]: targets for 0 po files that are out of date
building [man]: all manpages
updating environment: [new config] 4 added, 0 changed, 0 removed
reading sources... [100%] index
WARNING: autodoc: failed to import function 'connect' from module 'aiosqlite'; the following exception was raised:
No module named 'aiosqlite'
WARNING: autodoc: failed to import class 'Connection' from module 'aiosqlite'; the following exception was raised:
No module named 'aiosqlite'
WARNING: autodoc: failed to import class 'cursor.Cursor' from module 'aiosqlite'; the following exception was raised:
No module named 'aiosqlite'
WARNING: autodoc: failed to import exception 'Warning' from module 'aiosqlite'; the following exception was raised:
No module named 'aiosqlite'
WARNING: autodoc: failed to import exception 'Error' from module 'aiosqlite'; the following exception was raised:
No module named 'aiosqlite'
WARNING: autodoc: failed to import exception 'DatabaseError' from module 'aiosqlite'; the following exception was raised:
No module named 'aiosqlite'
WARNING: autodoc: failed to import exception 'IntegrityError' from module 'aiosqlite'; the following exception was raised:
No module named 'aiosqlite'
WARNING: autodoc: failed to import exception 'ProgrammingError' from module 'aiosqlite'; the following exception was raised:
No module named 'aiosqlite'
WARNING: autodoc: failed to import exception 'OperationalError' from module 'aiosqlite'; the following exception was raised:
No module named 'aiosqlite'
WARNING: autodoc: failed to import exception 'NotSupportedError' from module 'aiosqlite'; the following exception was raised:
No module named 'aiosqlite'
WARNING: autodoc: failed to import function 'register_adapter' from module 'aiosqlite'; the following exception was raised:
No module named 'aiosqlite'
WARNING: autodoc: failed to import function 'register_converter' from module 'aiosqlite'; the following exception was raised:
No module named 'aiosqlite'
CONTRIBUTING.md:34: WARNING: Inline emphasis start-string without end-string.
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-aiosqlite.3 { api changelog contributing } done
build succeeded, 13 warnings.

This issue can be fixed by patch like below:

--- a/docs/conf.py~     2022-04-30 11:25:41.000000000 +0000
+++ b/docs/conf.py      2022-04-30 11:26:27.942119042 +0000
@@ -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('..'))

 # -- Project information -----------------------------------------------------

That patch does exacly what is mentioned in comment above modified lines.

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:

[tkloczko@devel-g2v aiosqlite-0.17.0]$ /usr/bin/sphinx-build -n -T -b man docs build/sphinx/man
Running Sphinx v4.5.0
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [man]: all manpages
updating environment: 0 added, 1 changed, 0 removed
reading sources... [100%] api
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-aiosqlite.3 { api changelog contributing } /home/tkloczko/rpmbuild/BUILD/aiosqlite-0.17.0/aiosqlite/core.py:docstring of aiosqlite.core.connect:: WARNING: py:class reference target not found: asyncio.events.AbstractEventLoop
/home/tkloczko/rpmbuild/BUILD/aiosqlite-0.17.0/aiosqlite/core.py:docstring of aiosqlite.core.Connection:: WARNING: py:class reference target not found: asyncio.events.AbstractEventLoop
done
build succeeded, 2 warnings.

[amyreese]

re: building docs, the expected workflow is to run make html, which will generate a virtualenv with the supprted version of sphinx, and install aiosqlite appropriately so that sphinx can find it.

re: warnings, thank you, I’ll add -n to the make rules, and see about fixing the missing references. 🍻

[kloczek]

Outside python domain it is typical that documentation is generated out of source tree and not out of installed stuff. That patch fixes that. Other thing is that it tox execution takes time to assemply venv. That is not necessry and more complicated .. KISS principle. That patch as well guarantees that documentation will be generated out of source tree and not out of installed module.

Using that sys.path injection is even mentioned in sphinx copy.py exemple https://www.sphinx-doc.org/en/master/usage/configuration.html#example-of-configuration-file