From 5e3fb7d70fb67849ee55f5470ca7ffd0cffba947 Mon Sep 17 00:00:00 2001 From: Boni Lindsley Date: Sat, 24 Oct 2020 15:40:50 +0100 Subject: [PATCH] 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: - 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 | 36 +++++++++++++++---- .../test_PySide2_extras/test_posix_signal.py | 17 ++------- .../test_watchdog_wrapper.py | 18 ++-------- test_phile/test_configuration.py | 8 +---- test_phile/test_notify/test_cli.py | 16 ++------- test_phile/test_notify/test_gui.py | 30 ++-------------- test_phile/test_notify/test_notification.py | 8 +---- test_phile/test_tray/test_gui.py | 18 ++-------- test_phile/test_tray/test_tmux.py | 28 +++------------ test_phile/test_tray/test_tray_file.py | 10 +----- test_phile/test_watchdog_extras.py | 10 +----- 11 files changed, 49 insertions(+), 150 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 1a7b1f3..449db98 100644 --- a/docs/conf.py +++ b/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 = { diff --git a/test_phile/test_PySide2_extras/test_posix_signal.py b/test_phile/test_PySide2_extras/test_posix_signal.py index 244cbec..5e23a08 100644 --- a/test_phile/test_PySide2_extras/test_posix_signal.py +++ b/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: """ diff --git a/test_phile/test_PySide2_extras/test_watchdog_wrapper.py b/test_phile/test_PySide2_extras/test_watchdog_wrapper.py index c53a1b4..66c4564 100644 --- a/test_phile/test_PySide2_extras/test_watchdog_wrapper.py +++ b/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: """ diff --git a/test_phile/test_configuration.py b/test_phile/test_configuration.py index 7e09272..9df9184 100644 --- a/test_phile/test_configuration.py +++ b/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: """ diff --git a/test_phile/test_notify/test_cli.py b/test_phile/test_notify/test_cli.py index c6d498c..484eec8 100755 --- a/test_phile/test_notify/test_cli.py +++ b/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: """ diff --git a/test_phile/test_notify/test_gui.py b/test_phile/test_notify/test_gui.py index 72b83b1..6981939 100755 --- a/test_phile/test_notify/test_gui.py +++ b/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: """ diff --git a/test_phile/test_notify/test_notification.py b/test_phile/test_notify/test_notification.py index 8d6cbd2..ff75b3d 100644 --- a/test_phile/test_notify/test_notification.py +++ b/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: """ diff --git a/test_phile/test_tray/test_gui.py b/test_phile/test_tray/test_gui.py index 2b631bf..35b46fe 100755 --- a/test_phile/test_tray/test_gui.py +++ b/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: """ diff --git a/test_phile/test_tray/test_tmux.py b/test_phile/test_tray/test_tmux.py index 204ab4a..15078dc 100644 --- a/test_phile/test_tray/test_tmux.py +++ b/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: """ diff --git a/test_phile/test_tray/test_tray_file.py b/test_phile/test_tray/test_tray_file.py index 2bb3641..e50535c 100644 --- a/test_phile/test_tray/test_tray_file.py +++ b/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: """ diff --git a/test_phile/test_watchdog_extras.py b/test_phile/test_watchdog_extras.py index 9d65010..2a8b48a 100644 --- a/test_phile/test_watchdog_extras.py +++ b/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: """