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

@@ -16,7 +16,9 @@ from ahriman.models.user_identity import UserIdentity
 def build_status_failed() -> BuildStatus:
     """
     build result fixture with failed status
-    :return: failed build status test instance
+
+    Returns:
+        BuildStatus: failed build status test instance
     """
     return BuildStatus(BuildStatusEnum.Failed, 42)
 
@@ -25,7 +27,9 @@ def build_status_failed() -> BuildStatus:
 def counters() -> Counters:
     """
     counters fixture
-    :return: counters test instance
+
+    Returns:
+        Counters: counters test instance
     """
     return Counters(total=10,
                     unknown=1,
@@ -39,8 +43,12 @@ def counters() -> Counters:
 def internal_status(counters: Counters) -> InternalStatus:
     """
     internal status fixture
-    :param counters: counters fixture
-    :return: internal status test instance
+
+    Args:
+        counters(Counters): counters fixture
+
+    Returns:
+        InternalStatus: internal status test instance
     """
     return InternalStatus(architecture="x86_64",
                           packages=counters,
@@ -52,7 +60,9 @@ def internal_status(counters: Counters) -> InternalStatus:
 def package_tpacpi_bat_git() -> Package:
     """
     git package fixture
-    :return: git package test instance
+
+    Returns:
+        Package: git package test instance
     """
     return Package(
         base="tpacpi-bat-git",
@@ -65,8 +75,12 @@ def package_tpacpi_bat_git() -> Package:
 def pyalpm_handle(pyalpm_package_ahriman: MagicMock) -> MagicMock:
     """
     mock object for pyalpm
-    :param pyalpm_package_ahriman: mock object for pyalpm package
-    :return: pyalpm mock
+
+    Args:
+        pyalpm_package_ahriman(MagicMock): mock object for pyalpm package
+
+    Returns:
+        MagicMock: pyalpm mock
     """
     mock = MagicMock()
     mock.handle.load_pkg.return_value = pyalpm_package_ahriman
@@ -77,8 +91,12 @@ def pyalpm_handle(pyalpm_package_ahriman: MagicMock) -> MagicMock:
 def pyalpm_package_ahriman(package_ahriman: Package) -> MagicMock:
     """
     mock object for pyalpm package
-    :param package_ahriman: package fixture
-    :return: pyalpm package mock
+
+    Args:
+        package_ahriman(Package): package fixture
+
+    Returns:
+        MagicMock: pyalpm package mock
     """
     mock = MagicMock()
     type(mock).base = PropertyMock(return_value=package_ahriman.base)
@@ -93,8 +111,12 @@ def pyalpm_package_ahriman(package_ahriman: Package) -> MagicMock:
 def pyalpm_package_description_ahriman(package_description_ahriman: PackageDescription) -> MagicMock:
     """
     mock object for pyalpm package description
-    :param package_description_ahriman: package description fixture
-    :return: pyalpm package description mock
+
+    Args:
+        package_description_ahriman(PackageDescription): package description fixture
+
+    Returns:
+        MagicMock: pyalpm package description mock
     """
     mock = MagicMock()
     type(mock).arch = PropertyMock(return_value=package_description_ahriman.architecture)
@@ -114,6 +136,8 @@ def pyalpm_package_description_ahriman(package_description_ahriman: PackageDescr
 def user_identity() -> UserIdentity:
     """
     identity fixture
-    :return: user identity test instance
+
+    Returns:
+        UserIdentity: user identity test instance
     """
     return UserIdentity("username", int(time.time()) + 30)

tests/ahriman/models/test_aur_package.py

@@ -12,8 +12,12 @@ from ahriman.models.aur_package import AURPackage
 def _get_aur_data(resource_path_root: Path) -> Dict[str, Any]:
     """
     load package description from resource file
-    :param resource_path_root: path to resource root
-    :return: json descriptor
+
+    Args:
+        resource_path_root(Path): path to resource root
+
+    Returns:
+        Dict[str, Any]: json descriptor
     """
     response = (resource_path_root / "models" / "package_ahriman_aur").read_text()
     return json.loads(response)["results"][0]
@@ -22,8 +26,12 @@ def _get_aur_data(resource_path_root: Path) -> Dict[str, Any]:
 def _get_official_data(resource_path_root: Path) -> Dict[str, Any]:
     """
     load package description from resource file
-    :param resource_path_root: path to resource root
-    :return: json descriptor
+
+    Args:
+        resource_path_root(Path): path to resource root
+
+    Returns:
+        Dict[str, Any]: json descriptor
     """
     response = (resource_path_root / "models" / "package_akonadi_aur").read_text()
     return json.loads(response)["results"][0]

tests/ahriman/models/test_auth_settings.py

@@ -1,15 +1,11 @@
-import pytest
-
-from ahriman.core.exceptions import InvalidOption
 from ahriman.models.auth_settings import AuthSettings
 
 
 def test_from_option_invalid() -> None:
     """
-    must raise exception on invalid option
+    return disabled on invalid option
     """
-    with pytest.raises(InvalidOption, match=".* `invalid`$"):
-        AuthSettings.from_option("invalid")
+    assert AuthSettings.from_option("invalid") == AuthSettings.Disabled
 
 
 def test_from_option_valid() -> None:

tests/ahriman/models/test_package_source.py

@@ -9,9 +9,13 @@ from ahriman.models.package_source import PackageSource
 def _is_file_mock(is_any_file: bool, is_pkgbuild: bool) -> Callable[[Path], bool]:
     """
     helper to mock is_file method
-    :param is_any_file: value which will be return for any file
-    :param is_pkgbuild: value which will be return if PKGBUILD like path asked
-    :return: side effect function for the mocker object
+
+    Args:
+        is_any_file(bool): value which will be return for any file
+        is_pkgbuild(bool): value which will be return if PKGBUILD like path asked
+
+    Returns:
+        Callable[[Path], bool]: side effect function for the mocker object
     """
     side_effect: Callable[[Path], bool] = lambda source: is_pkgbuild if source.name == "PKGBUILD" else is_any_file
     return side_effect

tests/ahriman/models/test_report_settings.py

@@ -1,15 +1,11 @@
-import pytest
-
-from ahriman.core.exceptions import InvalidOption
 from ahriman.models.report_settings import ReportSettings
 
 
 def test_from_option_invalid() -> None:
     """
-    must raise exception on invalid option
+    must return disabled on invalid option
     """
-    with pytest.raises(InvalidOption, match=".* `invalid`$"):
-        ReportSettings.from_option("invalid")
+    assert ReportSettings.from_option("invalid") == ReportSettings.Disabled
 
 
 def test_from_option_valid() -> None:

tests/ahriman/models/test_repository_paths.py

@@ -14,9 +14,13 @@ from ahriman.models.repository_paths import RepositoryPaths
 def _get_owner(root: Path, same: bool) -> Callable[[Path], Tuple[int, int]]:
     """
     mocker function for owner definition
-    :param root: root directory
-    :param same: if True then returns the same as root directory and different otherwise
-    :return: function which can define ownership
+
+    Args:
+        root(Path): root directory
+        same(bool): if True then returns the same as root directory and different otherwise
+
+    Returns:
+        Callable[[Path], Tuple[int, int]]: function which can define ownership
     """
     root_owner = (42, 42)
     nonroot_owner = (42, 42) if same else (1, 1)

tests/ahriman/models/test_sign_settings.py

@@ -1,15 +1,11 @@
-import pytest
-
-from ahriman.core.exceptions import InvalidOption
 from ahriman.models.sign_settings import SignSettings
 
 
 def test_from_option_invalid() -> None:
     """
-    must raise exception on invalid option
+    must return disabled on invalid option
     """
-    with pytest.raises(InvalidOption, match=".* `invalid`$"):
-        SignSettings.from_option("invalid")
+    assert SignSettings.from_option("invalid") == SignSettings.Disabled
 
 
 def test_from_option_valid() -> None:

tests/ahriman/models/test_upload_settings.py

@@ -1,15 +1,11 @@
-import pytest
-
-from ahriman.core.exceptions import InvalidOption
 from ahriman.models.upload_settings import UploadSettings
 
 
 def test_from_option_invalid() -> None:
     """
-    must raise exception on invalid option
+    must return disabled on invalid option
     """
-    with pytest.raises(InvalidOption, match=".* `invalid`$"):
-        UploadSettings.from_option("invalid")
+    assert UploadSettings.from_option("invalid") == UploadSettings.Disabled
 
 
 def test_from_option_valid() -> None: