9.0.4: sphinx warnings reference target not found

[kloczek]

Forst of all it is not possible celanly use sphinx-build command to generate documentation

+ /usr/bin/sphinx-build -n -T -b man docs build/sphinx/man
Running Sphinx v4.5.0
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] 1 added, 0 changed, 0 removed
reading sources... [100%] index
WARNING: autodoc: failed to import module 'pyee'; the following exception was raised:
No module named 'pyee'
WARNING: autodoc: failed to import class 'EventEmitter' from module 'pyee'; the following exception was raised:
No module named 'pyee'
WARNING: autodoc: failed to import class 'asyncio.AsyncIOEventEmitter' from module 'pyee'; the following exception was raised:
No module named 'pyee'
WARNING: autodoc: failed to import class 'twisted.TwistedEventEmitter' from module 'pyee'; the following exception was raised:
No module named 'pyee'
WARNING: autodoc: failed to import class 'executor.ExecutorEventEmitter' from module 'pyee'; the following exception was raised:
No module named 'pyee'
WARNING: autodoc: failed to import class 'trio.TrioEventEmitter' from module 'pyee'; the following exception was raised:
No module named 'pyee'
WARNING: don't know which module to import for autodocumenting 'BaseEventEmitter' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
WARNING: autodoc: failed to import exception 'PyeeException' from module 'pyee'; the following exception was raised:
No module named 'pyee'
WARNING: autodoc: failed to import function 'uplift.uplift' from module 'pyee'; the following exception was raised:
No module named 'pyee'
WARNING: autodoc: failed to import function 'cls.on' from module 'pyee'; the following exception was raised:
No module named 'pyee'
WARNING: autodoc: failed to import function 'cls.evented' from module 'pyee'; the following exception was raised:
No module named 'pyee'
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... pyee.1 { } done
build succeeded, 12 warnings.

Thise warnings is possible to xix using patch like belo:

--- a/docs/conf.py~     2022-02-04 19:53:16.000000000 +0000
+++ b/docs/conf.py      2022-05-03 15:30:14.579697674 +0000
@@ -17,9 +17,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('..'))

 # -- General configuration ------------------------------------------------

This patch is doing exactly what is described 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:

+ /usr/bin/sphinx-build -n -T -b man docs build/sphinx/man
Running Sphinx v4.5.0
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] 1 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-pyee.3 { } /home/tkloczko/rpmbuild/BUILD/pyee-9.0.4/pyee/base.py:docstring of pyee.base.EventEmitter.add_listener:: WARNING: py:class reference target not found: pyee.base.Handler
/home/tkloczko/rpmbuild/BUILD/pyee-9.0.4/pyee/base.py:docstring of pyee.base.EventEmitter.add_listener:: WARNING: py:class reference target not found: pyee.base.Handler
/home/tkloczko/rpmbuild/BUILD/pyee-9.0.4/pyee/base.py:docstring of pyee.base.EventEmitter.listens_to:: WARNING: py:class reference target not found: pyee.base.Handler
/home/tkloczko/rpmbuild/BUILD/pyee-9.0.4/pyee/base.py:docstring of pyee.base.EventEmitter.listens_to:: WARNING: py:class reference target not found: pyee.base.Handler
/home/tkloczko/rpmbuild/BUILD/pyee-9.0.4/pyee/base.py:docstring of pyee.base.EventEmitter.on:: WARNING: py:class reference target not found: pyee.base.Handler
/home/tkloczko/rpmbuild/BUILD/pyee-9.0.4/pyee/base.py:docstring of pyee.base.EventEmitter.on:: WARNING: py:class reference target not found: pyee.base.Handler
/home/tkloczko/rpmbuild/BUILD/pyee-9.0.4/pyee/base.py:docstring of pyee.base.EventEmitter.on:: WARNING: py:class reference target not found: pyee.base.Handler
/home/tkloczko/rpmbuild/BUILD/pyee-9.0.4/pyee/base.py:docstring of pyee.base.EventEmitter.on:: WARNING: py:class reference target not found: pyee.base.Handler
/home/tkloczko/rpmbuild/BUILD/pyee-9.0.4/pyee/asyncio.py:docstring of pyee.asyncio.AsyncIOEventEmitter:: WARNING: py:class reference target not found: asyncio.events.AbstractEventLoop
/home/tkloczko/rpmbuild/BUILD/pyee-9.0.4/pyee/executor.py:docstring of pyee.executor.ExecutorEventEmitter:: WARNING: py:class reference target not found: concurrent.futures._base.Executor
/home/tkloczko/rpmbuild/BUILD/pyee-9.0.4/pyee/trio.py:docstring of pyee.trio.TrioEventEmitter:: WARNING: py:class reference target not found: trio.Nursery
/home/tkloczko/rpmbuild/BUILD/pyee-9.0.4/pyee/trio.py:docstring of pyee.trio.TrioEventEmitter:: WARNING: py:class reference target not found: AbstractAsyncContextManager
/home/tkloczko/rpmbuild/BUILD/pyee-9.0.4/pyee/trio.py:docstring of pyee.trio.TrioEventEmitter:: WARNING: py:class reference target not found: trio.Nursery
/home/tkloczko/rpmbuild/BUILD/pyee-9.0.4/pyee/uplift.py:docstring of pyee.uplift.uplift:: WARNING: py:class reference target not found: pyee.uplift.UpliftingEventEmitter
/home/tkloczko/rpmbuild/BUILD/pyee-9.0.4/pyee/uplift.py:docstring of pyee.uplift.uplift:: WARNING: py:class reference target not found: pyee.uplift.UpliftingEventEmitter
/home/tkloczko/rpmbuild/BUILD/pyee-9.0.4/pyee/cls.py:docstring of pyee.cls.evented:: WARNING: py:class reference target not found: pyee.cls.Cls
/home/tkloczko/rpmbuild/BUILD/pyee-9.0.4/pyee/cls.py:docstring of pyee.cls.evented:: WARNING: py:class reference target not found: pyee.cls.Cls
done
build succeeded, 18 warnings.

[jfhbrook]

I don't believe these changes are necessary.

To build the documentation, you're supposed to use the Makefile - make setup to create the virtualenv and make build_docs to build the docs. make serve_docs will serve them with http.server. You shouldn't, in fact, need sphinx-build at all.

But either way, I don't want to make these changes because they depend on paths. Instead, I want to depend on the module being installed into the current environment.

If you have some particular reason to use sphinx-build over make build_docs and can convince me, then we can work together to migrate. But you shouldn't need to mess with sys.path if pyee is installed in your env.

[kloczek]

As long as in your Makefile to the sphinx-build parameters will be added -n option you will be able to see the same warning.
That patch which alters sys.path guaranteees that documentation will be generated against code from source tree and not against installed pyee.
If you don't care about such detail that is fine. I'll keep that patch in build procedure.

If you have some particular reason to use sphinx-build over make build_docs and can convince me,

Reason is that this Makefile is not needed .. in other words that reason it is just KISS pronciple.

[jfhbrook]

In that case, I'm going to close this issue, as I have no intention of accepting a patch like this.

[kloczek]

In that case, I'm going to close this issue, as I have no intention of accepting a patch like this.

Reported warnings have nothing to do with reported warnings. That patch only improves the copy.py file to guarantee that it will produce ALWAYS documentation not out of installed module but out of code in source tree.

Did you ever try to use that -n switch to reproduce the issue? 🤔

[jfhbrook]

I did not, and I'm not going to. There is already a path for generating docs that works, and it's not my responsibility to support your preferred workflow. Sorry! Float the patches if you want them!

…

On Wed, May 4, 2022 at 11:32 AM Tomasz Kłoczko ***@***.***> wrote: In that case, I'm going to close this issue, as I have no intention of accepting a patch like this. Reported warnings has nothing to do with reported warnings. That patch only improves the copy.py file to guarantee that it will produce ALWAYS documentation not out of installed module but out of code in source tree. Did you ever try to use that -n switch to reproduce the issue? 🤔 — Reply to this email directly, view it on GitHub <#115 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAOBQG4QRLA2I5JICZMUW3VIKKARANCNFSM5U7JF2WQ> . You are receiving this because you modified the open/close state.Message ID: ***@***.***>

[kloczek]

Wrong references are mot about paths ..