gorakhargosh/watchdog

2.1.9: sphinx warnings `reference target not found`

Open

#898 opened on Jun 10, 2022

View on GitHub
 (2 comments) (0 reactions) (0 assignees)Python (6,090 stars) (684 forks)batch import
Good first issueHelp welcome :)documentation

Description

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/source build/sphinx/man
Running Sphinx v5.0.1
making output directory... done
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%] quickstart
/home/tkloczko/rpmbuild/BUILD/watchdog-2.1.9/docs/source/installation.rst:12: WARNING: Inline substitution_reference start-string without end-string.
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-watchdog.3 { installation quickstart api hacking } /home/tkloczko/rpmbuild/BUILD/watchdog-2.1.9/docs/source/quickstart.rst:23: WARNING: py:meth reference target not found: watchdog.observers.Observer.schedule
/home/tkloczko/rpmbuild/BUILD/watchdog-2.1.9/src/watchdog/observers/api.py:docstring of watchdog.observers.api.EventQueue:1: WARNING: py:class reference target not found: watchdog.utils.bricks.SkipRepeatsQueue
/home/tkloczko/rpmbuild/BUILD/watchdog-2.1.9/src/watchdog/observers/api.py:docstring of watchdog.observers.api.EventQueue:1: WARNING: py:class reference target not found: FileSystemEvent
/home/tkloczko/rpmbuild/BUILD/watchdog-2.1.9/src/watchdog/observers/api.py:docstring of watchdog.observers.api.EventEmitter:7: WARNING: py:class reference target not found: watchdog.events.EventQueue
/home/tkloczko/rpmbuild/BUILD/watchdog-2.1.9/src/watchdog/observers/api.py:docstring of watchdog.observers.api.EventDispatcher.dispatch_events:1: WARNING: py:class reference target not found: queue.Empty
/home/tkloczko/rpmbuild/BUILD/watchdog-2.1.9/src/watchdog/observers/api.py:docstring of watchdog.observers.api.EventDispatcher.dispatch_events:9: WARNING: py:class reference target not found: queue.Empty
/home/tkloczko/rpmbuild/BUILD/watchdog-2.1.9/src/watchdog/observers/api.py:docstring of watchdog.observers.api.BaseObserver.dispatch_events:1: WARNING: py:class reference target not found: queue.Empty
/home/tkloczko/rpmbuild/BUILD/watchdog-2.1.9/src/watchdog/observers/api.py:docstring of watchdog.observers.api.BaseObserver.dispatch_events:9: WARNING: py:class reference target not found: queue.Empty
/home/tkloczko/rpmbuild/BUILD/watchdog-2.1.9/src/watchdog/observers/api.py:docstring of watchdog.observers.api.BaseObserver.on_thread_stop:1: WARNING: py:meth reference target not found: stop
/home/tkloczko/rpmbuild/BUILD/watchdog-2.1.9/src/watchdog/observers/api.py:docstring of watchdog.observers.api.BaseObserver.on_thread_stop:1: WARNING: py:meth reference target not found: stop
<unknown>:1: WARNING: py:class reference target not found: watchdog.observers.inotify.InotifyObserver
/home/tkloczko/rpmbuild/BUILD/watchdog-2.1.9/src/watchdog/observers/__init__.py:docstring of watchdog.observers:29: WARNING: py:class reference target not found: inotify.InotifyObserver
/home/tkloczko/rpmbuild/BUILD/watchdog-2.1.9/src/watchdog/observers/__init__.py:docstring of watchdog.observers:30: WARNING: py:class reference target not found: fsevents.FSEventsObserver
/home/tkloczko/rpmbuild/BUILD/watchdog-2.1.9/src/watchdog/observers/__init__.py:docstring of watchdog.observers:31: WARNING: py:class reference target not found: kqueue.KqueueObserver
/home/tkloczko/rpmbuild/BUILD/watchdog-2.1.9/src/watchdog/observers/__init__.py:docstring of watchdog.observers:32: WARNING: py:class reference target not found: read_directory_changes.WindowsApiObserver
/home/tkloczko/rpmbuild/BUILD/watchdog-2.1.9/src/watchdog/observers/__init__.py:docstring of watchdog.observers:29: WARNING: py:class reference target not found: inotify.InotifyObserver
/home/tkloczko/rpmbuild/BUILD/watchdog-2.1.9/src/watchdog/observers/__init__.py:docstring of watchdog.observers:30: WARNING: py:class reference target not found: fsevents.FSEventsObserver
/home/tkloczko/rpmbuild/BUILD/watchdog-2.1.9/src/watchdog/observers/__init__.py:docstring of watchdog.observers:31: WARNING: py:class reference target not found: kqueue.KqueueObserver
/home/tkloczko/rpmbuild/BUILD/watchdog-2.1.9/src/watchdog/observers/__init__.py:docstring of watchdog.observers:32: WARNING: py:class reference target not found: read_directory_changes.WindowsApiObserver
/home/tkloczko/rpmbuild/BUILD/watchdog-2.1.9/src/watchdog/utils/__init__.py:docstring of watchdog.utils.BaseThread:1: WARNING: py:class reference target not found: threading.Thread
/home/tkloczko/rpmbuild/BUILD/watchdog-2.1.9/src/watchdog/utils/dirsnapshot.py:docstring of watchdog.utils.dirsnapshot.DirectorySnapshot.stat_info:4: WARNING: py:func reference target not found: mtime
/home/tkloczko/rpmbuild/BUILD/watchdog-2.1.9/src/watchdog/utils/dirsnapshot.py:docstring of watchdog.utils.dirsnapshot.DirectorySnapshot.stat_info:4: WARNING: py:func reference target not found: isdir
/home/tkloczko/rpmbuild/BUILD/watchdog-2.1.9/src/watchdog/tricks/__init__.py:docstring of watchdog.tricks.LoggerTrick.on_any_event:6: WARNING: py:class reference target not found: FileSystemEvent
/home/tkloczko/rpmbuild/BUILD/watchdog-2.1.9/src/watchdog/tricks/__init__.py:docstring of watchdog.tricks.LoggerTrick.on_created:6: WARNING: py:class reference target not found: DirCreatedEvent
/home/tkloczko/rpmbuild/BUILD/watchdog-2.1.9/src/watchdog/tricks/__init__.py:docstring of watchdog.tricks.LoggerTrick.on_created:6: WARNING: py:class reference target not found: FileCreatedEvent
/home/tkloczko/rpmbuild/BUILD/watchdog-2.1.9/src/watchdog/tricks/__init__.py:docstring of watchdog.tricks.LoggerTrick.on_deleted:6: WARNING: py:class reference target not found: DirDeletedEvent
/home/tkloczko/rpmbuild/BUILD/watchdog-2.1.9/src/watchdog/tricks/__init__.py:docstring of watchdog.tricks.LoggerTrick.on_deleted:6: WARNING: py:class reference target not found: FileDeletedEvent
/home/tkloczko/rpmbuild/BUILD/watchdog-2.1.9/src/watchdog/tricks/__init__.py:docstring of watchdog.tricks.LoggerTrick.on_modified:6: WARNING: py:class reference target not found: DirModifiedEvent
/home/tkloczko/rpmbuild/BUILD/watchdog-2.1.9/src/watchdog/tricks/__init__.py:docstring of watchdog.tricks.LoggerTrick.on_modified:6: WARNING: py:class reference target not found: FileModifiedEvent
/home/tkloczko/rpmbuild/BUILD/watchdog-2.1.9/src/watchdog/tricks/__init__.py:docstring of watchdog.tricks.LoggerTrick.on_moved:6: WARNING: py:class reference target not found: DirMovedEvent
/home/tkloczko/rpmbuild/BUILD/watchdog-2.1.9/src/watchdog/tricks/__init__.py:docstring of watchdog.tricks.LoggerTrick.on_moved:6: WARNING: py:class reference target not found: FileMovedEvent
/home/tkloczko/rpmbuild/BUILD/watchdog-2.1.9/src/watchdog/tricks/__init__.py:docstring of watchdog.tricks.ShellCommandTrick.on_any_event:6: WARNING: py:class reference target not found: FileSystemEvent
/home/tkloczko/rpmbuild/BUILD/watchdog-2.1.9/src/watchdog/tricks/__init__.py:docstring of watchdog.tricks.AutoRestartTrick.on_any_event:6: WARNING: py:class reference target not found: FileSystemEvent
done
build succeeded, 34 warnings.

You can peak on fixes that kind of issues in other projects https://github.com/latchset/jwcrypto/pull/289 https://github.com/click-contrib/sphinx-click/commit/abc31069 https://github.com/latchset/jwcrypto/pull/289 https://github.com/RDFLib/rdflib-sqlalchemy/issues/95 https://github.com/sissaschool/elementpath/commit/bf869d9e https://github.com/jaraco/cssutils/issues/21

Contributor guide

Tech stack
python
Domain
documentation
Issue type
documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
fresh
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
PythonSphinxreStructuredText
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
70
Research direction
The issue reports multiple Sphinx warnings about missing reference targets in documentation. The fix involves adding intersphinx mappings for external projects (e.g., Python standard library) or correcting the reST markup to point to existing definitions. Specific files to examine: docs/source/installation.rst, docs/source/quickstart.rst, src/watchdog/observers/api.py, src/watchdog/observers/ init .py, src/watchdog/utils/ init .py, src/watchdog/utils/dirsnapshot.py, src/watchdog/tricks/ init .py. The warnings indicate missing py:class and py:meth references. One approach is to configure intersphinx in docs/conf.py to link to Python and watchdog's own API. For internal references, ensure that the documented classes and methods are properly included in the Sphinx autodoc extraction.