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/core/alpm/remote/conftest.py

@@ -9,7 +9,9 @@ from ahriman.core.alpm.remote.remote import Remote
 def aur() -> AUR:
     """
     aur helper fixture
-    :return: aur helper instance
+
+    Returns:
+        AUR: aur helper instance
     """
     return AUR()
 
@@ -18,7 +20,9 @@ def aur() -> AUR:
 def official() -> Official:
     """
     official repository fixture
-    :return: official repository helper instance
+
+    Returns:
+        Official: official repository helper instance
     """
     return Official()
 
@@ -27,6 +31,8 @@ def official() -> Official:
 def remote() -> Remote:
     """
     official repository fixture
-    :return: official repository helper instance
+
+    Returns:
+        Remote: official repository helper instance
     """
     return Remote()

tests/ahriman/core/alpm/remote/test_aur.py

@@ -14,8 +14,12 @@ from ahriman.models.aur_package import AURPackage
 def _get_response(resource_path_root: Path) -> str:
     """
     load response from resource file
-    :param resource_path_root: path to resource root
-    :return: response text
+
+    Args:
+        resource_path_root(Path): path to resource root
+
+    Returns:
+        str: response text
     """
     return (resource_path_root / "models" / "package_ahriman_aur").read_text()
 

tests/ahriman/core/alpm/remote/test_official.py

@@ -14,8 +14,12 @@ from ahriman.models.aur_package import AURPackage
 def _get_response(resource_path_root: Path) -> str:
     """
     load response from resource file
-    :param resource_path_root: path to resource root
-    :return: response text
+
+    Args:
+        resource_path_root(Path): path to resource root
+
+    Returns:
+        str: response text
     """
     return (resource_path_root / "models" / "package_akonadi_aur").read_text()
 

tests/ahriman/core/auth/conftest.py

@@ -10,9 +10,13 @@ from ahriman.core.database.sqlite import SQLite
 def mapping(configuration: Configuration, database: SQLite) -> Mapping:
     """
     auth provider fixture
-    :param configuration: configuration fixture
-    :param database: database fixture
-    :return: auth service instance
+
+    Args:
+        configuration(Configuration): configuration fixture
+        database(SQLite): database fixture
+
+    Returns:
+        Mapping: auth service instance
     """
     return Mapping(configuration, database)
 
@@ -21,9 +25,13 @@ def mapping(configuration: Configuration, database: SQLite) -> Mapping:
 def oauth(configuration: Configuration, database: SQLite) -> OAuth:
     """
     OAuth provider fixture
-    :param configuration: configuration fixture
-    :param database: database fixture
-    :return: OAuth2 service instance
+
+    Args:
+        configuration(Configuration): configuration fixture
+        database(SQLite): database fixture
+
+    Returns:
+        OAuth: OAuth2 service instance
     """
     configuration.set("web", "address", "https://example.com")
     return OAuth(configuration, database)

tests/ahriman/core/conftest.py

@@ -2,7 +2,6 @@ import pytest
 
 from ahriman.core.alpm.pacman import Pacman
 from ahriman.core.alpm.repo import Repo
-from ahriman.core.auth.auth import Auth
 from ahriman.core.build_tools.task import Task
 from ahriman.core.configuration import Configuration
 from ahriman.core.tree import Leaf
@@ -14,8 +13,12 @@ from ahriman.models.repository_paths import RepositoryPaths
 def leaf_ahriman(package_ahriman: Package) -> Leaf:
     """
     fixture for tree leaf with package
-    :param package_ahriman: package fixture
-    :return: tree leaf test instance
+
+    Args:
+        package_ahriman(Package): package fixture
+
+    Returns:
+        Leaf: tree leaf test instance
     """
     return Leaf(package_ahriman, set())
 
@@ -24,8 +27,12 @@ def leaf_ahriman(package_ahriman: Package) -> Leaf:
 def leaf_python_schedule(package_python_schedule: Package) -> Leaf:
     """
     fixture for tree leaf with package
-    :param package_python_schedule: package fixture
-    :return: tree leaf test instance
+
+    Args:
+        package_python_schedule(Package): package fixture
+
+    Returns:
+        Leaf: tree leaf test instance
     """
     return Leaf(package_python_schedule, set())
 
@@ -34,8 +41,12 @@ def leaf_python_schedule(package_python_schedule: Package) -> Leaf:
 def pacman(configuration: Configuration) -> Pacman:
     """
     fixture for pacman wrapper
-    :param configuration: configuration fixture
-    :return: pacman wrapper test instance
+
+    Args:
+        configuration(Configuration): configuration fixture
+
+    Returns:
+        Pacman: pacman wrapper test instance
     """
     return Pacman(configuration)
 
@@ -44,9 +55,13 @@ def pacman(configuration: Configuration) -> Pacman:
 def repo(configuration: Configuration, repository_paths: RepositoryPaths) -> Repo:
     """
     fixture for repository wrapper
-    :param configuration: configuration fixture
-    :param repository_paths: repository paths fixture
-    :return: repository wrapper test instance
+
+    Args:
+        configuration(Configuration): configuration fixture
+        repository_paths(RepositoryPaths): repository paths fixture
+
+    Returns:
+        Repo: repository wrapper test instance
     """
     return Repo(configuration.get("repository", "name"), repository_paths, [])
 
@@ -55,9 +70,13 @@ def repo(configuration: Configuration, repository_paths: RepositoryPaths) -> Rep
 def task_ahriman(package_ahriman: Package, configuration: Configuration, repository_paths: RepositoryPaths) -> Task:
     """
     fixture for built task
-    :param package_ahriman: package fixture
-    :param configuration: configuration fixture
-    :param repository_paths: repository paths fixture
-    :return: built task test instance
+
+    Args:
+        package_ahriman(Package): package fixture
+        configuration(Configuration): configuration fixture
+        repository_paths(RepositoryPaths): repository paths fixture
+
+    Returns:
+        Task: built task test instance
     """
     return Task(package_ahriman, configuration, repository_paths)

tests/ahriman/core/database/conftest.py

@@ -8,6 +8,8 @@ from unittest.mock import MagicMock
 def connection() -> Connection:
     """
     mock object for sqlite3 connection
-    :return: sqlite3 connection test instance
+
+    Returns:
+        Connection: sqlite3 connection test instance
     """
     return MagicMock()

tests/ahriman/core/database/migrations/conftest.py

@@ -9,7 +9,11 @@ from ahriman.core.database.migrations import Migrations
 def migrations(connection: Connection) -> Migrations:
     """
     fixture for migrations object
-    :param connection: sqlite connection fixture
-    :return: migrations test instance
+
+    Args:
+        connection(Connection): sqlite connection fixture
+
+    Returns:
+        Migrations: migrations test instance
     """
     return Migrations(connection)

tests/ahriman/core/formatters/conftest.py

@@ -17,8 +17,12 @@ from ahriman.models.user import User
 def aur_package_ahriman_printer(aur_package_ahriman: AURPackage) -> AurPrinter:
     """
     fixture for AUR package printer
-    :param aur_package_ahriman: AUR package fixture
-    :return: AUR package printer test instance
+
+    Args:
+        aur_package_ahriman(AURPackage): AUR package fixture
+
+    Returns:
+        AurPrinter: AUR package printer test instance
     """
     return AurPrinter(aur_package_ahriman)
 
@@ -27,7 +31,9 @@ def aur_package_ahriman_printer(aur_package_ahriman: AURPackage) -> AurPrinter:
 def configuration_printer() -> ConfigurationPrinter:
     """
     fixture for configuration printer
-    :return: configuration printer test instance
+
+    Returns:
+        ConfigurationPrinter: configuration printer test instance
     """
     return ConfigurationPrinter("section", {"key_one": "value_one", "key_two": "value_two"})
 
@@ -36,8 +42,12 @@ def configuration_printer() -> ConfigurationPrinter:
 def package_ahriman_printer(package_ahriman: Package) -> PackagePrinter:
     """
     fixture for package printer
-    :param package_ahriman: package fixture
-    :return: package printer test instance
+
+    Args:
+        package_ahriman(Package): package fixture
+
+    Returns:
+        PackagePrinter: package printer test instance
     """
     return PackagePrinter(package_ahriman, BuildStatus())
 
@@ -46,7 +56,9 @@ def package_ahriman_printer(package_ahriman: Package) -> PackagePrinter:
 def status_printer() -> StatusPrinter:
     """
     fixture for build status printer
-    :return: build status printer test instance
+
+    Returns:
+        StatusPrinter: build status printer test instance
     """
     return StatusPrinter(BuildStatus())
 
@@ -55,7 +67,9 @@ def status_printer() -> StatusPrinter:
 def string_printer() -> StringPrinter:
     """
     fixture for any string printer
-    :return: any string printer test instance
+
+    Returns:
+        StringPrinter: any string printer test instance
     """
     return StringPrinter("hello, world")
 
@@ -64,7 +78,12 @@ def string_printer() -> StringPrinter:
 def update_printer(package_ahriman: Package) -> UpdatePrinter:
     """
     fixture for build status printer
-    :return: build status printer test instance
+
+    Args:
+        package_ahriman(Package): package fixture
+
+    Returns:
+        UpdatePrinter: build status printer test instance
     """
     return UpdatePrinter(package_ahriman, None)
 
@@ -73,7 +92,11 @@ def update_printer(package_ahriman: Package) -> UpdatePrinter:
 def user_printer(user: User) -> UserPrinter:
     """
     fixture for user printer
-    :param user: user fixture
-    :return: user printer test instance
+
+    Args:
+        user(User): user fixture
+
+    Returns:
+        UserPrinter: user printer test instance
     """
     return UserPrinter(user)

tests/ahriman/core/repository/conftest.py

@@ -15,10 +15,14 @@ from ahriman.core.repository.update_handler import UpdateHandler
 def cleaner(configuration: Configuration, database: SQLite, mocker: MockerFixture) -> Cleaner:
     """
     fixture for cleaner
-    :param configuration: configuration fixture
-    :param database: database fixture
-    :param mocker: mocker object
-    :return: cleaner test instance
+
+    Args:
+        configuration(Configuration): configuration fixture
+        database(SQLite): database fixture
+        mocker(MockerFixture): mocker object
+
+    Returns:
+        Cleaner: cleaner test instance
     """
     mocker.patch("ahriman.models.repository_paths.RepositoryPaths.tree_create")
     return Cleaner("x86_64", configuration, database, no_report=True, unsafe=False)
@@ -28,10 +32,14 @@ def cleaner(configuration: Configuration, database: SQLite, mocker: MockerFixtur
 def executor(configuration: Configuration, database: SQLite, mocker: MockerFixture) -> Executor:
     """
     fixture for executor
-    :param configuration: configuration fixture
-    :param database: database fixture
-    :param mocker: mocker object
-    :return: executor test instance
+
+    Args:
+        configuration(Configuration): configuration fixture
+        database(SQLite): database fixture
+        mocker(MockerFixture): mocker object
+
+    Returns:
+        Executor: executor test instance
     """
     mocker.patch("ahriman.core.repository.cleaner.Cleaner.clear_cache")
     mocker.patch("ahriman.core.repository.cleaner.Cleaner.clear_chroot")
@@ -45,10 +53,14 @@ def executor(configuration: Configuration, database: SQLite, mocker: MockerFixtu
 def repository(configuration: Configuration, database: SQLite, mocker: MockerFixture) -> Repository:
     """
     fixture for repository
-    :param configuration: configuration fixture
-    :param database: database fixture
-    :param mocker: mocker object
-    :return: repository test instance
+
+    Args:
+        configuration(Configuration): configuration fixture
+        database(SQLite): database fixture
+        mocker(MockerFixture): mocker object
+
+    Returns:
+        Repository: repository test instance
     """
     mocker.patch("ahriman.models.repository_paths.RepositoryPaths.tree_create")
     return Repository("x86_64", configuration, database, no_report=True, unsafe=False)
@@ -58,9 +70,13 @@ def repository(configuration: Configuration, database: SQLite, mocker: MockerFix
 def properties(configuration: Configuration, database: SQLite) -> Properties:
     """
     fixture for properties
-    :param configuration: configuration fixture
-    :param database: database fixture
-    :return: properties test instance
+
+    Args:
+        configuration(Configuration): configuration fixture
+        database(SQLite): database fixture
+
+    Returns:
+        Properties: properties test instance
     """
     return Properties("x86_64", configuration, database, no_report=True, unsafe=False)
 
@@ -69,10 +85,14 @@ def properties(configuration: Configuration, database: SQLite) -> Properties:
 def update_handler(configuration: Configuration, database: SQLite, mocker: MockerFixture) -> UpdateHandler:
     """
     fixture for update handler
-    :param configuration: configuration fixture
-    :param database: database fixture
-    :param mocker: mocker object
-    :return: update handler test instance
+
+    Args:
+        configuration(Configuration): configuration fixture
+        database(SQLite): database fixture
+        mocker(MockerFixture): mocker object
+
+    Returns:
+        UpdateHandler: update handler test instance
     """
     mocker.patch("ahriman.core.repository.cleaner.Cleaner.clear_cache")
     mocker.patch("ahriman.core.repository.cleaner.Cleaner.clear_chroot")

tests/ahriman/core/repository/test_cleaner.py

@@ -11,7 +11,9 @@ from ahriman.core.repository.cleaner import Cleaner
 def _mock_clear(mocker: MockerFixture) -> None:
     """
     mocker helper for clear function
-    :param mocker: mocker object
+
+    Args:
+        mocker(MockerFixture): mocker object
     """
     mocker.patch("pathlib.Path.iterdir", return_value=[Path("a"), Path("b"), Path("c")])
     mocker.patch("shutil.rmtree")

tests/ahriman/core/sign/conftest.py

@@ -8,8 +8,12 @@ from ahriman.core.sign.gpg import GPG
 def gpg(configuration: Configuration) -> GPG:
     """
     fixture for empty GPG
-    :param configuration: configuration fixture
-    :return: GPG test instance
+
+    Args:
+        configuration(Configuration): configuration fixture
+
+    Returns:
+        GPG: GPG test instance
     """
     return GPG("x86_64", configuration)
 
@@ -18,8 +22,12 @@ def gpg(configuration: Configuration) -> GPG:
 def gpg_with_key(gpg: GPG) -> GPG:
     """
     fixture for correct GPG
-    :param gpg: empty GPG fixture
-    :return: GPG test instance
+
+    Args:
+        gpg(GPG): empty GPG fixture
+
+    Returns:
+        GPG: GPG test instance
     """
     gpg.default_key = "key"
     return gpg

tests/ahriman/core/sign/test_gpg.py

@@ -4,6 +4,7 @@ import requests
 from pathlib import Path
 from pytest_mock import MockerFixture
 
+from ahriman.core.configuration import Configuration
 from ahriman.core.sign.gpg import GPG
 from ahriman.models.sign_settings import SignSettings
 
@@ -63,6 +64,18 @@ def test_sign_command(gpg_with_key: GPG) -> None:
     assert gpg_with_key.sign_command(Path("a"), gpg_with_key.default_key)
 
 
+def test_sign_options(configuration: Configuration) -> None:
+    """
+    must correctly parse sign options
+    """
+    configuration.set_option("sign", "target", "repository disabled")
+    configuration.set_option("sign", "key", "default-key")
+
+    target, default_key = GPG.sign_options(configuration)
+    assert target == {SignSettings.Repository}
+    assert default_key == "default-key"
+
+
 def test_key_download(gpg: GPG, mocker: MockerFixture) -> None:
     """
     must download the key from public server

tests/ahriman/core/status/conftest.py

@@ -5,12 +5,13 @@ from ahriman.core.status.client import Client
 from ahriman.core.status.web_client import WebClient
 
 
-# fixtures
 @pytest.fixture
 def client() -> Client:
     """
     fixture for dummy client
-    :return: dummy client test instance
+
+    Returns:
+        Client: dummy client test instance
     """
     return Client()
 
@@ -19,8 +20,12 @@ def client() -> Client:
 def web_client(configuration: Configuration) -> WebClient:
     """
     fixture for web client
-    :param configuration: configuration fixture
-    :return: web client test instance
+
+    Args:
+        configuration(Configuration): configuration fixture
+
+    Returns:
+        WebClient: web client test instance
     """
     configuration.set("web", "port", "8080")
     return WebClient(configuration)

tests/ahriman/core/upload/conftest.py

@@ -17,8 +17,12 @@ _s3_object = namedtuple("s3_object", ["key", "e_tag", "delete"])
 def github(configuration: Configuration) -> Github:
     """
     fixture for github synchronization
-    :param configuration: configuration fixture
-    :return: github test instance
+
+    Args:
+        configuration(Configuration): configuration fixture
+
+    Returns:
+        Github: github test instance
     """
     return Github("x86_64", configuration, "github:x86_64")
 
@@ -27,7 +31,9 @@ def github(configuration: Configuration) -> Github:
 def github_release() -> Dict[str, Any]:
     """
     fixture for the github release object
-    :return: github test release object
+
+    Returns:
+        Dict[str, Any]: github test release object
     """
     return {
         "url": "release_url",
@@ -47,8 +53,12 @@ def github_release() -> Dict[str, Any]:
 def rsync(configuration: Configuration) -> Rsync:
     """
     fixture for rsync synchronization
-    :param configuration: configuration fixture
-    :return: rsync test instance
+
+    Args:
+        configuration(Configuration): configuration fixture
+
+    Returns:
+        Rsync: rsync test instance
     """
     return Rsync("x86_64", configuration, "rsync")
 
@@ -57,8 +67,12 @@ def rsync(configuration: Configuration) -> Rsync:
 def s3(configuration: Configuration) -> S3:
     """
     fixture for S3 synchronization
-    :param configuration: configuration fixture
-    :return: S3 test instance
+
+    Args:
+        configuration(Configuration): configuration fixture
+
+    Returns:
+        S3: S3 test instance
     """
     return S3("x86_64", configuration, "customs3")
 
@@ -67,7 +81,9 @@ def s3(configuration: Configuration) -> S3:
 def s3_remote_objects() -> List[_s3_object]:
     """
     fixture for boto3 like S3 objects
-    :return: boto3 like S3 objects test instance
+
+    Returns:
+        List[_s3_object]: boto3 like S3 objects test instance
     """
     delete_mock = MagicMock()
     return list(map(lambda item: _s3_object(f"x86_64/{item}", f"\"{item}\"", delete_mock), ["a", "b", "c"]))