Docstring update (#58)

* migrate docstrings from reST to google format

* add raises note

Also change behaviour of the `from_option` method to fallback to
disabled instead of raising exception on unknown option

* fix part of warnings for sphinx

* make identation a bit more readable

* review fixes

* add verbose description for properties to make them parsed by sphinx extenstion

* add demo sphinx generator

tests/ahriman/application/handlers/test_handler_add.py

@@ -13,8 +13,12 @@ from ahriman.models.result import Result
 def _default_args(args: argparse.Namespace) -> argparse.Namespace:
     """
     default arguments for these test cases
-    :param args: command line arguments fixture
-    :return: generated arguments for these test cases
+
+    Args:
+        args(argparse.Namespace): command line arguments fixture
+
+    Returns:
+        argparse.Namespace: generated arguments for these test cases
     """
     args.package = []
     args.exit_code = False

tests/ahriman/application/handlers/test_handler_backup.py

@@ -12,8 +12,12 @@ from ahriman.models.repository_paths import RepositoryPaths
 def _default_args(args: argparse.Namespace) -> argparse.Namespace:
     """
     default arguments for these test cases
-    :param args: command line arguments fixture
-    :return: generated arguments for these test cases
+
+    Args:
+        args(argparse.Namespace): command line arguments fixture
+
+    Returns:
+        argparse.Namespace: generated arguments for these test cases
     """
     args.path = Path("result.tar.gz")
     return args

tests/ahriman/application/handlers/test_handler_clean.py

@@ -9,8 +9,12 @@ from ahriman.core.configuration import Configuration
 def _default_args(args: argparse.Namespace) -> argparse.Namespace:
     """
     default arguments for these test cases
-    :param args: command line arguments fixture
-    :return: generated arguments for these test cases
+
+    Args:
+        args(argparse.Namespace): command line arguments fixture
+
+    Returns:
+        argparse.Namespace: generated arguments for these test cases
     """
     args.cache = False
     args.chroot = False

tests/ahriman/application/handlers/test_handler_help.py

@@ -10,8 +10,12 @@ from ahriman.core.configuration import Configuration
 def _default_args(args: argparse.Namespace) -> argparse.Namespace:
     """
     default arguments for these test cases
-    :param args: command line arguments fixture
-    :return: generated arguments for these test cases
+
+    Args:
+        args(argparse.Namespace): command line arguments fixture
+
+    Returns:
+        argparse.Namespace: generated arguments for these test cases
     """
     args.parser = _parser
     args.command = None

tests/ahriman/application/handlers/test_handler_key_import.py

@@ -9,8 +9,12 @@ from ahriman.core.configuration import Configuration
 def _default_args(args: argparse.Namespace) -> argparse.Namespace:
     """
     default arguments for these test cases
-    :param args: command line arguments fixture
-    :return: generated arguments for these test cases
+
+    Args:
+        args(argparse.Namespace): command line arguments fixture
+
+    Returns:
+        argparse.Namespace: generated arguments for these test cases
     """
     args.key = "0xE989490C"
     args.key_server = "pgp.mit.edu"

tests/ahriman/application/handlers/test_handler_patch.py

@@ -13,8 +13,12 @@ from ahriman.models.package import Package
 def _default_args(args: argparse.Namespace) -> argparse.Namespace:
     """
     default arguments for these test cases
-    :param args: command line arguments fixture
-    :return: generated arguments for these test cases
+
+    Args:
+        args(argparse.Namespace): command line arguments fixture
+
+    Returns:
+        argparse.Namespace: generated arguments for these test cases
     """
     args.package = "ahriman"
     args.exit_code = False

tests/ahriman/application/handlers/test_handler_rebuild.py

@@ -14,8 +14,12 @@ from ahriman.models.result import Result
 def _default_args(args: argparse.Namespace) -> argparse.Namespace:
     """
     default arguments for these test cases
-    :param args: command line arguments fixture
-    :return: generated arguments for these test cases
+
+    Args:
+        args(argparse.Namespace): command line arguments fixture
+
+    Returns:
+        argparse.Namespace: generated arguments for these test cases
     """
     args.depends_on = []
     args.dry_run = False

tests/ahriman/application/handlers/test_handler_remove.py

@@ -9,8 +9,12 @@ from ahriman.core.configuration import Configuration
 def _default_args(args: argparse.Namespace) -> argparse.Namespace:
     """
     default arguments for these test cases
-    :param args: command line arguments fixture
-    :return: generated arguments for these test cases
+
+    Args:
+        args(argparse.Namespace): command line arguments fixture
+
+    Returns:
+        argparse.Namespace: generated arguments for these test cases
     """
     args.package = []
     return args

tests/ahriman/application/handlers/test_handler_remove_unknown.py

@@ -10,8 +10,12 @@ from ahriman.models.package import Package
 def _default_args(args: argparse.Namespace) -> argparse.Namespace:
     """
     default arguments for these test cases
-    :param args: command line arguments fixture
-    :return: generated arguments for these test cases
+
+    Args:
+        args(argparse.Namespace): command line arguments fixture
+
+    Returns:
+        argparse.Namespace: generated arguments for these test cases
     """
     args.dry_run = False
     args.info = False

tests/ahriman/application/handlers/test_handler_report.py

@@ -10,8 +10,12 @@ from ahriman.models.result import Result
 def _default_args(args: argparse.Namespace) -> argparse.Namespace:
     """
     default arguments for these test cases
-    :param args: command line arguments fixture
-    :return: generated arguments for these test cases
+
+    Args:
+        args(argparse.Namespace): command line arguments fixture
+
+    Returns:
+        argparse.Namespace: generated arguments for these test cases
     """
     args.target = []
     return args

tests/ahriman/application/handlers/test_handler_restore.py

@@ -11,8 +11,12 @@ from ahriman.core.configuration import Configuration
 def _default_args(args: argparse.Namespace) -> argparse.Namespace:
     """
     default arguments for these test cases
-    :param args: command line arguments fixture
-    :return: generated arguments for these test cases
+
+    Args:
+        args(argparse.Namespace): command line arguments fixture
+
+    Returns:
+        argparse.Namespace: generated arguments for these test cases
     """
     args.path = Path("result.tar.gz")
     args.output = Path.cwd()

tests/ahriman/application/handlers/test_handler_search.py

@@ -14,8 +14,12 @@ from ahriman.models.aur_package import AURPackage
 def _default_args(args: argparse.Namespace) -> argparse.Namespace:
     """
     default arguments for these test cases
-    :param args: command line arguments fixture
-    :return: generated arguments for these test cases
+
+    Args:
+        args(argparse.Namespace): command line arguments fixture
+
+    Returns:
+        argparse.Namespace: generated arguments for these test cases
     """
     args.search = ["ahriman"]
     args.exit_code = False

tests/ahriman/application/handlers/test_handler_setup.py

@@ -14,8 +14,12 @@ from ahriman.models.sign_settings import SignSettings
 def _default_args(args: argparse.Namespace) -> argparse.Namespace:
     """
     default arguments for these test cases
-    :param args: command line arguments fixture
-    :return: generated arguments for these test cases
+
+    Args:
+        args(argparse.Namespace): command line arguments fixture
+
+    Returns:
+        argparse.Namespace: generated arguments for these test cases
     """
     args.build_as_user = "ahriman"
     args.build_command = "ahriman"

tests/ahriman/application/handlers/test_handler_sign.py

@@ -9,8 +9,12 @@ from ahriman.core.configuration import Configuration
 def _default_args(args: argparse.Namespace) -> argparse.Namespace:
     """
     default arguments for these test cases
-    :param args: command line arguments fixture
-    :return: generated arguments for these test cases
+
+    Args:
+        args(argparse.Namespace): command line arguments fixture
+
+    Returns:
+        argparse.Namespace: generated arguments for these test cases
     """
     args.package = []
     return args

tests/ahriman/application/handlers/test_handler_status.py

@@ -12,8 +12,12 @@ from ahriman.models.package import Package
 def _default_args(args: argparse.Namespace) -> argparse.Namespace:
     """
     default arguments for these test cases
-    :param args: command line arguments fixture
-    :return: generated arguments for these test cases
+
+    Args:
+        args(argparse.Namespace): command line arguments fixture
+
+    Returns:
+        argparse.Namespace: generated arguments for these test cases
     """
     args.ahriman = True
     args.exit_code = False

tests/ahriman/application/handlers/test_handler_status_update.py

@@ -12,8 +12,12 @@ from ahriman.models.package import Package
 def _default_args(args: argparse.Namespace) -> argparse.Namespace:
     """
     default arguments for these test cases
-    :param args: command line arguments fixture
-    :return: generated arguments for these test cases
+
+    Args:
+        args(argparse.Namespace): command line arguments fixture
+
+    Returns:
+        argparse.Namespace: generated arguments for these test cases
     """
     args.package = None
     args.action = Action.Update

tests/ahriman/application/handlers/test_handler_sync.py

@@ -9,8 +9,12 @@ from ahriman.core.configuration import Configuration
 def _default_args(args: argparse.Namespace) -> argparse.Namespace:
     """
     default arguments for these test cases
-    :param args: command line arguments fixture
-    :return: generated arguments for these test cases
+
+    Args:
+        args(argparse.Namespace): command line arguments fixture
+
+    Returns:
+        argparse.Namespace: generated arguments for these test cases
     """
     args.target = []
     return args

tests/ahriman/application/handlers/test_handler_unsafe_commands.py

@@ -6,14 +6,17 @@ from pytest_mock import MockerFixture
 from ahriman.application.ahriman import _parser
 from ahriman.application.handlers import UnsafeCommands
 from ahriman.core.configuration import Configuration
-from ahriman.core.exceptions import ExitCode
 
 
 def _default_args(args: argparse.Namespace) -> argparse.Namespace:
     """
     default arguments for these test cases
-    :param args: command line arguments fixture
-    :return: generated arguments for these test cases
+
+    Args:
+        args(argparse.Namespace): command line arguments fixture
+
+    Returns:
+        argparse.Namespace: generated arguments for these test cases
     """
     args.parser = _parser
     args.command = None
@@ -49,19 +52,22 @@ def test_run_check(args: argparse.Namespace, configuration: Configuration, mocke
     check_mock.assert_called_once_with("clean", ["command"], pytest.helpers.anyvar(int))
 
 
-def test_check_unsafe() -> None:
+def test_check_unsafe(mocker: MockerFixture) -> None:
     """
     must check if command is unsafe
     """
-    with pytest.raises(ExitCode):
-        UnsafeCommands.check_unsafe("repo-clean", ["repo-clean"], _parser())
+    check_mock = mocker.patch("ahriman.application.handlers.handler.Handler.check_if_empty")
+    UnsafeCommands.check_unsafe("repo-clean", ["repo-clean"], _parser())
+    check_mock.assert_called_once_with(True, True)
 
 
-def test_check_unsafe_safe() -> None:
+def test_check_unsafe_safe(mocker: MockerFixture) -> None:
     """
     must check if command is safe
     """
+    check_mock = mocker.patch("ahriman.application.handlers.handler.Handler.check_if_empty")
     UnsafeCommands.check_unsafe("package-status", ["repo-clean"], _parser())
+    check_mock.assert_called_once_with(True, False)
 
 
 def test_get_unsafe_commands() -> None:

tests/ahriman/application/handlers/test_handler_update.py

@@ -14,8 +14,12 @@ from ahriman.models.result import Result
 def _default_args(args: argparse.Namespace) -> argparse.Namespace:
     """
     default arguments for these test cases
-    :param args: command line arguments fixture
-    :return: generated arguments for these test cases
+
+    Args:
+        args(argparse.Namespace): command line arguments fixture
+
+    Returns:
+        argparse.Namespace: generated arguments for these test cases
     """
     args.package = []
     args.dry_run = False

tests/ahriman/application/handlers/test_handler_user.py

@@ -16,8 +16,12 @@ from ahriman.models.user_access import UserAccess
 def _default_args(args: argparse.Namespace) -> argparse.Namespace:
     """
     default arguments for these test cases
-    :param args: command line arguments fixture
-    :return: generated arguments for these test cases
+
+    Args:
+        args(argparse.Namespace): command line arguments fixture
+
+    Returns:
+        argparse.Namespace: generated arguments for these test cases
     """
     args.username = "user"
     args.action = Action.Update

tests/ahriman/application/handlers/test_handler_web.py

@@ -10,8 +10,12 @@ from ahriman.core.configuration import Configuration
 def _default_args(args: argparse.Namespace) -> argparse.Namespace:
     """
     default arguments for these test cases
-    :param args: command line arguments fixture
-    :return: generated arguments for these test cases
+
+    Args:
+        args(argparse.Namespace): command line arguments fixture
+
+    Returns:
+        argparse.Namespace: generated arguments for these test cases
     """
     args.parser = lambda: True
     return args