I am working on a project that is using pyqtSignals and documenting things with automodule.
I have a class like the following:
from PyQt5.QtCore import pyqtSignal
from PyQt5.QtWidgets import QWidget
class SomeView(QWidget):
mySignal = pyqtSignal(str)
def __init__(self, parent=None):
super().__init__(parent)
Then I have something like this:
code package
=======================
Submodules
----------
code.SomeView.py module
------------------------------------------
.. automodule:: code.SomeView
:members:
:undoc-members:
:show-inheritance:
I expect for the resulting documentation to have something like:
class code.SomeView(*args: Any, **kwargs: Any):
mySignal (pyqtSignal)
When I try to make the documentation, I get this warning:
WARNING: Inline emphasis start-string without end-string.
There is no emphasis start-string, because there is no docstring at all, so this makes no sense.
If I go to the HTML, it has filled in some unexpected docstring, which I can only guess is the source of the errors. That docstring is:
pyqtSignal(*types, name: str = …, revision: int = …, arguments: Sequence = …) -> PYQT_SIGNAL
types is normally a sequence of individual types. Each type is either a type object or a string that is the name of a C++ type. Alternatively each type could itself be a sequence of types each describing a different overloaded signal. name is the optional C++ name of the signal. If it is not specified then the name of the class attribute that is bound to the signal is used. revision is the optional revision of the signal that is exported to QML. If it is not specified then 0 is used. arguments is the optional sequence of the names of the signal’s arguments.
Searching the web, there are a few other repos whose public docs have this exact string in them, so this is likely not being set on our repo.
I have tried adding this signal to the excluded list.
code package
=======================
Submodules
----------
code.SomeView.py module
------------------------------------------
.. automodule:: code.SomeView
:members:
:undoc-members:
:exclude-members: mySignal
:show-inheritance:
That removes the warning, but now the signal isn't documented.
I have tried adding a nonsense docstring,
from PyQt5.QtCore import pyqtSignal
from PyQt5.QtWidgets import QWidget
class SomeView(QWidget):
mySignal = pyqtSignal(str)
"""
"""
def __init__(self, parent=None):
super().__init__(parent)
This removes the warning, except in my actual production code now there are dozens of these "no-op" strings floating around making it look ugly. We don't really want to add actual docstrings either, for largely the same reason.
Declaring the signals inside the __init__ stops the sphinx warning, but is not allowed within python. The signal has to be declared where it is.
Is there any way to make sphinx stop producing this default docstring? Where is this default even coming from? How can I change this default?