docs: Separate class and __init__ docs

-   Conceptually, class documentation describes the class usage
    and `__init__` describes constructor usage.
    It was previously decided to merge them
    because having them separated would list their signatures twice.
    Once in the class description, and once in the `__init__` method.

    A side-effect of this previous workaround was that
    the merged content, if `__init__` does not have a docstring,
    would try to inherit the `__init__` docstring from the parent class.
    That means suppressing this inheritance
    would require a vacuous `__init__`.
    This has to be duplicated in, for example, all unit tests,
    because they do not require custom constructors.
    Maintaining this is takes more effort and scaffolding
    than it is worth.
    So it is now separated
    and the signature will be duplicated in the documentation instead,
    albeit not a desired outcome.

    Ideally, the class heading would not list the signature.
    There is an open issue for this.
    See: <sphinx-doc/sphinx#4257>

-   Show dunder (and base classes) in documentation
    This is necessary to show documentation for `__init__` separately,
    now that it is not included in the class documentation part.

    As a side-effect, this also shows other custom dunder methods.
    However, `__dict__`, `__module__` and `__weakref__`
    are excluded still, as they are not generally useful.

-   Ignore inherited methods.
    In particular, do not inherit documentation
    for the newly shown `__init__`.
    This is usually undesirable,
    as the documentations may be third-party,
    and may break builds if their docstrings are not compatible.

    Note that this flag does not stop the merged class docstring
    from inheriting `__init__`,
    so this alone would not solve the aforementioned issue.

-   Remove types from signature.
    This will add parameter and return types into description
    if the parameters are not there already.
    Previously, the types are included in the signature,
    which makes the signature unreadable.
    This should help with the duplication mentioned above
    by reducing the duplicated noise a little.

docs/conf.py

@@ -82,7 +82,7 @@
 
 # ## Extension: sphinx.ext.autodoc
 
-autoclass_content = 'both'
+autoclass_content = 'class'
 """
 This value selects what content will be inserted
 into the main body of an autoclass directive.
@@ -107,18 +107,42 @@
 """
 
 autodoc_default_options = {
-    #'exclude-members',
+    # Do not show these members.
+    # Note that documentation for `__init__` can still be added
+    # by setting `autoclass_content` to `both` or `init`.
+    'exclude-members': '__dict__, __module__, __weakref__',
+    # Add all documented members. Boolean or 'var1, var2'.
+    'members': True,
+    # Add dunder members.
+    'special-members': True,
+    # Insert list of base classes.
+    'show-inheritance': True,
+    # Include undocumented members
+    'undoc-members': True,
     #'ignore-module-all',
     #'imported-members',
     #'inherited-members',
-    'members': True,
     #'member-order',
     #'private-members',
-    #'special-members':,
-    #'show-inheritance',
-    'undoc-members': True,
 }
 
+autodoc_inherit_docstrings = False
+
+autodoc_typehints = 'description'
+"""
+How to represents typehints.
+
+The setting takes the following values:
+
+-   'signature': Show typehints as its signature (default)
+-   'description': Show typehints as content of function or method
+-   'none': Do not show typehints
+
+New in version 2.1.
+
+New in version 3.0: New option 'description' is added.
+"""
+
 # ## Extension: sphinx.ext.intersphinx
 
 intersphinx_mapping = {

test_phile/test_PySide2_extras/test_posix_signal.py

@@ -43,15 +43,10 @@ def get_wakeup_fd() -> int:
 
 class TestInstallNoopSignalHandler(unittest.TestCase):
     """
-    Unit test for
+    Tests
     :class:`~phile.PySide2_extras.posix_signal.install_noop_signal_handler`.
     """
 
-    def __init__(self, *args, **kwargs):
-        """"""
-        # This method is created purely to overwrite default docstring.
-        super().__init__(*args, **kwargs)
-
     def setUp(self) -> None:
         """Remember the current signal handler to be restored later."""
         self.sigint_handler = signal.getsignal(signal.SIGINT)
@@ -80,15 +75,7 @@ def test_call(self) -> None:
     platform_can_handle_sigint, 'Cannot handle SIGINT on this platform.'
 )
 class TestPosixSignal(unittest.TestCase):
-    """
-    Unit test for
-    :class:`~phile.PySide2_extras.posix_signal.PosixSignal`.
-    """
-
-    def __init__(self, *args, **kwargs):
-        """"""
-        # This method is created purely to overwrite default docstring.
-        super().__init__(*args, **kwargs)
+    """Tests :class:`~phile.PySide2_extras.posix_signal.PosixSignal`."""
 
     def setUp(self) -> None:
         """

test_phile/test_PySide2_extras/test_watchdog_wrapper.py

@@ -32,15 +32,7 @@
 
 
 class TestFileSystemSignalEmitter(unittest.TestCase):
-    """
-    Unit test for :class:`~phile.PySide2_extras.FileSystemSignalEmitter`.
-    """
-
-    def __init__(self, *args, **kwargs) -> None:
-        """
-        """
-        # This method is created purely to overwrite default docstring.
-        super().__init__(*args, **kwargs)
+    """Tests :class:`~phile.PySide2_extras.FileSystemSignalEmitter`."""
 
     def setUp(self) -> None:
         """
@@ -161,13 +153,7 @@ def test_start_with_custom_observer(self) -> None:
 
 
 class TestFileSystemMonitor(unittest.TestCase):
-    """Unit test for :class:`~phile.PySide2_extras.FileSystemMonitor."""
-
-    def __init__(self, *args, **kwargs) -> None:
-        """
-        """
-        # This method is created purely to overwrite default docstring.
-        super().__init__(*args, **kwargs)
+    """Tests :class:`~phile.PySide2_extras.FileSystemMonitor."""
 
     def setUp(self) -> None:
         """

test_phile/test_configuration.py

@@ -15,13 +15,7 @@
 
 
 class TestConfiguration(unittest.TestCase):
-    """Unit test for :class:`~phile.tray.Configuration`."""
-
-    def __init__(self, *args, **kwargs) -> None:
-        """
-        """
-        # This method is created purely to overwrite default docstring.
-        super().__init__(*args, **kwargs)
+    """Tests :class:`~phile.tray.Configuration`."""
 
     def setUp(self) -> None:
         """

test_phile/test_notify/test_cli.py

@@ -24,13 +24,7 @@
 
 
 class TestCreateArgumentParser(unittest.TestCase):
-    """Unit test for :func:`~phile.notify.cli.create_argument_parser`."""
-
-    def __init__(self, *args, **kwargs) -> None:
-        """
-        """
-        # This method is created purely to overwrite default docstring.
-        super().__init__(*args, **kwargs)
+    """Tests :func:`~phile.notify.cli.create_argument_parser`."""
 
     def setUp(self) -> None:
         self.argument_parser = create_argument_parser()
@@ -81,13 +75,7 @@ def test_write(self) -> None:
 
 
 class TestProcessArguments(unittest.TestCase):
-    """Unit test for :func:`~phile.notify.cli.process_arguments`."""
-
-    def __init__(self, *args, **kwargs) -> None:
-        """
-        """
-        # This method is created purely to overwrite default docstring.
-        super().__init__(*args, **kwargs)
+    """Tests :func:`~phile.notify.cli.process_arguments`."""
 
     def setUp(self) -> None:
         """

test_phile/test_notify/test_gui.py

@@ -33,15 +33,7 @@
 
 
 class TestNotificationMdiSubWindow(unittest.TestCase):
-    """
-    Unit test for :class:`~phile.notify.gui.NotificationMdiSubWindow`.
-    """
-
-    def __init__(self, *args, **kwargs) -> None:
-        """
-        """
-        # This method is created purely to overwrite default docstring.
-        super().__init__(*args, **kwargs)
+    """Tests :class:`~phile.notify.gui.NotificationMdiSubWindow`."""
 
     def setUp(self) -> None:
         """
@@ -152,15 +144,7 @@ def test_closed_signal(self) -> None:
 
 
 class TestNotificationMdi(unittest.TestCase):
-    """
-    Unit test for :class:`~phile.notify.gui.NotificationMdi`.
-    """
-
-    def __init__(self, *args, **kwargs) -> None:
-        """
-        """
-        # This method is created purely to overwrite default docstring.
-        super().__init__(*args, **kwargs)
+    """Tests :class:`~phile.notify.gui.NotificationMdi`."""
 
     def setUp(self) -> None:
         """
@@ -510,15 +494,7 @@ def test_resizeEvent_in_tabbed_view_mode(self) -> None:
 
 
 class TestMainWindow(unittest.TestCase):
-    """
-    Unit test for :class:`~phile.notify.gui.MainWindow`.
-    """
-
-    def __init__(self, *args, **kwargs) -> None:
-        """
-        """
-        # This method is created purely to overwrite default docstring.
-        super().__init__(*args, **kwargs)
+    """Tests for :class:`~phile.notify.gui.MainWindow`."""
 
     def setUp(self) -> None:
         """

test_phile/test_notify/test_notification.py

@@ -17,13 +17,7 @@
 
 
 class TestNotification(unittest.TestCase):
-    """Unit test for :class:`~phile.notify.cli.Notification`."""
-
-    def __init__(self, *args, **kwargs) -> None:
-        """
-        """
-        # This method is created purely to overwrite default docstring.
-        super().__init__(*args, **kwargs)
+    """Tests :class:`~phile.notify.cli.Notification`."""
 
     def setUp(self) -> None:
         """

test_phile/test_tray/test_gui.py

@@ -32,13 +32,7 @@
 
 
 class TestSetIconPaths(unittest.TestCase):
-    """Unit test for :class:`~phile.tray.set_icon_paths`."""
-
-    def __init__(self, *args, **kwargs) -> None:
-        """
-        """
-        # This method is created purely to overwrite default docstring.
-        super().__init__(*args, **kwargs)
+    """Tests :class:`~phile.tray.set_icon_paths`."""
 
     def setUp(self) -> None:
         """
@@ -79,15 +73,7 @@ def test_call(self) -> None:
 
 
 class TestGuiIconList(unittest.TestCase):
-    """
-    Unit test for :class:`~phile.tray.gui.GuiIconList`.
-    """
-
-    def __init__(self, *args, **kwargs) -> None:
-        """
-        """
-        # This method is created purely to overwrite default docstring.
-        super().__init__(*args, **kwargs)
+    """Tests :class:`~phile.tray.gui.GuiIconList`."""
 
     def setUp(self) -> None:
         """

test_phile/test_tray/test_tmux.py

@@ -41,17 +41,12 @@
 
 class TestCommandBuilder(unittest.TestCase):
     """
-    Unit test for :class:`~phile.tray.tmux.CommandBuilder`.
+    Tests :class:`~phile.tray.tmux.CommandBuilder`.
 
     Ensures the tmux command string returned from the class methods
     are as expected.
     """
 
-    def __init__(self, *args, **kwargs) -> None:
-        """"""
-        # This method is created purely to overwrite default docstring.
-        super().__init__(*args, **kwargs)
-
     def test_exit_client(self) -> None:
         self.assertEqual(CommandBuilder.exit_client(), '')
 
@@ -97,12 +92,7 @@ def test_set_global_status_right(self) -> None:
 
 
 class TestTimedeltaToSeconds(unittest.TestCase):
-    """Unit test for :class:`~phile.tray.tmux.timedelta_to_seconds`."""
-
-    def __init__(self, *args, **kwargs) -> None:
-        """"""
-        # This method is created purely to overwrite default docstring.
-        super().__init__(*args, **kwargs)
+    """Tests :class:`~phile.tray.tmux.timedelta_to_seconds`."""
 
     def test_timedelta(self) -> None:
         """Convert :class:`~datetime.timedelta` to seconds."""
@@ -118,7 +108,7 @@ def test_none(self) -> None:
 
 class TestControlMode(unittest.TestCase):
     """
-    Unit test for :class:`~phile.tray.tmux.ControlMode`.
+    Tests :class:`~phile.tray.tmux.ControlMode`.
 
     Also tests the functions :meth:`~phile.tray.tmux.get_server_pid`
     and :meth:`~phile.tray.tmux.kill_server`,
@@ -132,11 +122,6 @@ class TestControlMode(unittest.TestCase):
     in :meth:`~TestControlMode.test_initialisation` as well.
     """
 
-    def __init__(self, *args, **kwargs) -> None:
-        """"""
-        # This method is created purely to overwrite default docstring.
-        super().__init__(*args, **kwargs)
-
     def setUp(self) -> None:
         """
         Create a tmux server instance before each method test.
@@ -351,12 +336,7 @@ def test_function_kill_server_failing(self) -> None:
 
 
 class TestIconList(unittest.TestCase):
-    """Unit test for :class:`~phile.tray.tmux.IconList`."""
-
-    def __init__(self, *args, **kwargs) -> None:
-        """"""
-        # This method is created purely to overwrite default docstring.
-        super().__init__(*args, **kwargs)
+    """Tests :class:`~phile.tray.tmux.IconList`."""
 
     def setUp(self) -> None:
         """

test_phile/test_tray/test_tray_file.py

@@ -16,15 +16,7 @@
 
 
 class TestTrayFile(unittest.TestCase):
-    """
-    Unit test for :class:`~phile.notify.tray.TrayFile`.
-    """
-
-    def __init__(self, *args, **kwargs) -> None:
-        """
-        """
-        # This method is created purely to overwrite default docstring.
-        super().__init__(*args, **kwargs)
+    """Tests :class:`~phile.notify.tray.TrayFile`."""
 
     def setUp(self) -> None:
         """

test_phile/test_watchdog_extras.py

@@ -25,15 +25,7 @@
 
 
 class TestObserver(unittest.TestCase):
-    """
-    Unit test for :class:`~phile.PySide2_extras.Observer`.
-    """
-
-    def __init__(self, *args, **kwargs) -> None:
-        """
-        """
-        # This method is created purely to overwrite default docstring.
-        super().__init__(*args, **kwargs)
+    """Tests :class:`~phile.PySide2_extras.Observer`."""
 
     def setUp(self) -> None:
         """