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/application/conftest.py

@@ -13,10 +13,14 @@ from ahriman.core.database.sqlite import SQLite
 def application_packages(configuration: Configuration, database: SQLite, mocker: MockerFixture) -> Packages:
     """
     fixture for application with package functions
-    :param configuration: configuration fixture
-    :param database: database fixture
-    :param mocker: mocker object
-    :return: application test instance
+
+    Args:
+        configuration(Configuration): configuration fixture
+        database(SQLite): database fixture
+        mocker(MockerFixture): mocker object
+
+    Returns:
+        Packages: application test instance
     """
     mocker.patch("ahriman.models.repository_paths.RepositoryPaths.tree_create")
     mocker.patch("ahriman.core.database.sqlite.SQLite.load", return_value=database)
@@ -27,10 +31,14 @@ def application_packages(configuration: Configuration, database: SQLite, mocker:
 def application_properties(configuration: Configuration, database: SQLite, mocker: MockerFixture) -> Properties:
     """
     fixture for application with properties only
-    :param configuration: configuration fixture
-    :param database: database fixture
-    :param mocker: mocker object
-    :return: application test instance
+
+    Args:
+        configuration(Configuration): configuration fixture
+        database(SQLite): database fixture
+        mocker(MockerFixture): mocker object
+
+    Returns:
+        Properties: application test instance
     """
     mocker.patch("ahriman.models.repository_paths.RepositoryPaths.tree_create")
     mocker.patch("ahriman.core.database.sqlite.SQLite.load", return_value=database)
@@ -41,10 +49,14 @@ def application_properties(configuration: Configuration, database: SQLite, mocke
 def application_repository(configuration: Configuration, database: SQLite, mocker: MockerFixture) -> Repository:
     """
     fixture for application with repository functions
-    :param configuration: configuration fixture
-    :param database: database fixture
-    :param mocker: mocker object
-    :return: application test instance
+
+    Args:
+        configuration(Configuration): configuration fixture
+        database(SQLite): database fixture
+        mocker(MockerFixture): mocker object
+
+    Returns:
+        Repository: application test instance
     """
     mocker.patch("ahriman.models.repository_paths.RepositoryPaths.tree_create")
     mocker.patch("ahriman.core.database.sqlite.SQLite.load", return_value=database)

tests/ahriman/application/conftest.py

@@ -14,10 +14,14 @@ from ahriman.core.database.sqlite import SQLite
 def application(configuration: Configuration, database: SQLite, mocker: MockerFixture) -> Application:
     """
     fixture for application
-    :param configuration: configuration fixture
-    :param database: database fixture
-    :param mocker: mocker object
-    :return: application test instance
+
+    Args:
+        configuration(Configuration): configuration fixture
+        database(SQLite): database fixture
+        mocker(MockerFixture): mocker object
+
+    Returns:
+        Application: application test instance
     """
     mocker.patch("ahriman.models.repository_paths.RepositoryPaths.tree_create")
     mocker.patch("ahriman.core.database.sqlite.SQLite.load", return_value=database)
@@ -28,7 +32,9 @@ def application(configuration: Configuration, database: SQLite, mocker: MockerFi
 def args() -> argparse.Namespace:
     """
     fixture for command line arguments
-    :return: command line arguments test instance
+
+    Returns:
+        argparse.Namespace: command line arguments test instance
     """
     return argparse.Namespace(architecture=None, lock=None, force=False, unsafe=False, no_report=True)
 
@@ -37,9 +43,13 @@ def args() -> argparse.Namespace:
 def lock(args: argparse.Namespace, configuration: Configuration) -> Lock:
     """
     fixture for file lock
-    :param args: command line arguments fixture
-    :param configuration: configuration fixture
-    :return: file lock test instance
+
+    Args:
+        args(argparse.Namespace): command line arguments fixture
+        configuration(Configuration): configuration fixture
+
+    Returns:
+        Lock: file lock test instance
     """
     return Lock(args, "x86_64", configuration)
 
@@ -48,6 +58,8 @@ def lock(args: argparse.Namespace, configuration: Configuration) -> Lock:
 def parser() -> argparse.ArgumentParser:
     """
     fixture for command line arguments parser
-    :return: command line arguments parser test instance
+
+    Returns:
+        argparse.ArgumentParser: command line arguments parser test instance
     """
     return _parser()

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