From 58e7ede7443e3322232f5f6f30a7f61415b0cacf Mon Sep 17 00:00:00 2001
From: Evgeniy Alekseev <i@arcanis.me>
Date: Sun, 17 Apr 2022 19:30:50 +0300
Subject: [PATCH] add verbose description for properties to make them parsed by
 sphinx extenstion

---
 src/ahriman/core/alpm/repo.py             |  2 ++
 src/ahriman/core/auth/oauth.py            |  2 ++
 src/ahriman/core/configuration.py         |  6 ++++++
 src/ahriman/core/sign/gpg.py              |  2 ++
 src/ahriman/core/status/watcher.py        |  2 ++
 src/ahriman/core/status/web_client.py     |  6 ++++++
 src/ahriman/core/tree.py                  |  2 ++
 src/ahriman/models/auth_settings.py       |  2 ++
 src/ahriman/models/migration_result.py    |  8 +++++---
 src/ahriman/models/package.py             | 18 ++++++++++++++++--
 src/ahriman/models/package_description.py |  2 ++
 src/ahriman/models/repository_paths.py    | 18 ++++++++++++++----
 src/ahriman/models/result.py              |  6 ++++++
 src/ahriman/web/views/base.py             | 10 ++++++++++
 14 files changed, 77 insertions(+), 9 deletions(-)

diff --git a/src/ahriman/core/alpm/repo.py b/src/ahriman/core/alpm/repo.py
index 2c315ee9..72d52fdf 100644
--- a/src/ahriman/core/alpm/repo.py
+++ b/src/ahriman/core/alpm/repo.py
@@ -59,6 +59,8 @@ class Repo:
     @property
     def repo_path(self) -> Path:
         """
+        get full path to the repository database
+
         Returns:
             Path: path to repository database
         """
diff --git a/src/ahriman/core/auth/oauth.py b/src/ahriman/core/auth/oauth.py
index 1ce3b988..55dbb607 100644
--- a/src/ahriman/core/auth/oauth.py
+++ b/src/ahriman/core/auth/oauth.py
@@ -64,6 +64,8 @@ class OAuth(Mapping):
     @property
     def auth_control(self) -> str:
         """
+        get authorization html control
+
         Returns:
             str: login control as html code to insert
         """
diff --git a/src/ahriman/core/configuration.py b/src/ahriman/core/configuration.py
index da6b42e3..dcb85447 100644
--- a/src/ahriman/core/configuration.py
+++ b/src/ahriman/core/configuration.py
@@ -65,6 +65,8 @@ class Configuration(configparser.RawConfigParser):
     @property
     def include(self) -> Path:
         """
+        get full path to include directory
+
         Returns:
             Path: path to directory with configuration includes
         """
@@ -73,6 +75,8 @@ class Configuration(configparser.RawConfigParser):
     @property
     def logging_path(self) -> Path:
         """
+        get full path to logging configuration
+
         Returns:
             Path: path to logging configuration
         """
@@ -81,6 +85,8 @@ class Configuration(configparser.RawConfigParser):
     @property
     def repository_paths(self) -> RepositoryPaths:
         """
+        construct RepositoryPaths instance based on the configuration
+
         Returns:
             RepositoryPaths: repository paths instance
         """
diff --git a/src/ahriman/core/sign/gpg.py b/src/ahriman/core/sign/gpg.py
index 39a4be98..4351afd2 100644
--- a/src/ahriman/core/sign/gpg.py
+++ b/src/ahriman/core/sign/gpg.py
@@ -59,6 +59,8 @@ class GPG:
     @property
     def repository_sign_args(self) -> List[str]:
         """
+        get command line arguments based on settings
+
         Returns:
             List[str]: command line arguments for repo-add command to sign database
         """
diff --git a/src/ahriman/core/status/watcher.py b/src/ahriman/core/status/watcher.py
index d9f99786..651a503a 100644
--- a/src/ahriman/core/status/watcher.py
+++ b/src/ahriman/core/status/watcher.py
@@ -63,6 +63,8 @@ class Watcher:
     @property
     def packages(self) -> List[Tuple[Package, BuildStatus]]:
         """
+        get current known packages list
+
         Returns:
             List[Tuple[Package, BuildStatus]]: list of packages together with their statuses
         """
diff --git a/src/ahriman/core/status/web_client.py b/src/ahriman/core/status/web_client.py
index b3613da4..6ba79f72 100644
--- a/src/ahriman/core/status/web_client.py
+++ b/src/ahriman/core/status/web_client.py
@@ -60,6 +60,8 @@ class WebClient(Client):
     @property
     def _ahriman_url(self) -> str:
         """
+        get url for the service status api
+
         Returns:
             str: full url for web service for ahriman service itself
         """
@@ -68,6 +70,8 @@ class WebClient(Client):
     @property
     def _login_url(self) -> str:
         """
+        get url for the login api
+
         Returns:
             str: full url for web service to login
         """
@@ -76,6 +80,8 @@ class WebClient(Client):
     @property
     def _status_url(self) -> str:
         """
+        get url for the status api
+
         Returns:
             str: full url for web service for status
         """
diff --git a/src/ahriman/core/tree.py b/src/ahriman/core/tree.py
index da838730..eb2c5fcb 100644
--- a/src/ahriman/core/tree.py
+++ b/src/ahriman/core/tree.py
@@ -50,6 +50,8 @@ class Leaf:
     @property
     def items(self) -> Iterable[str]:
         """
+        extract all packages from the leaf
+
         Returns:
             Iterable[str]: packages containing in this leaf
         """
diff --git a/src/ahriman/models/auth_settings.py b/src/ahriman/models/auth_settings.py
index 3a300d4e..d698b91e 100644
--- a/src/ahriman/models/auth_settings.py
+++ b/src/ahriman/models/auth_settings.py
@@ -57,6 +57,8 @@ class AuthSettings(Enum):
     @property
     def is_enabled(self) -> bool:
         """
+        get enabled flag
+
         Returns:
             bool: False in case if authorization is disabled and True otherwise
         """
diff --git a/src/ahriman/models/migration_result.py b/src/ahriman/models/migration_result.py
index d260d296..16178992 100644
--- a/src/ahriman/models/migration_result.py
+++ b/src/ahriman/models/migration_result.py
@@ -38,11 +38,10 @@ class MigrationResult:
     @property
     def is_outdated(self) -> bool:
         """
+        check migration and check if there are pending migrations
+
         Returns:
             bool: True in case if it requires migrations and False otherwise
-
-        Raises:
-            MigrationError: if old version is newer than new one or negative
         """
         self.validate()
         return self.new_version > self.old_version
@@ -50,6 +49,9 @@ class MigrationResult:
     def validate(self) -> None:
         """
         perform version validation
+
+        Raises:
+            MigrationError: if old version is newer than new one or negative
         """
         if self.old_version < 0 or self.old_version > self.new_version:
             raise MigrationError(f"Invalid current schema version, expected less or equal to {self.new_version}, "
diff --git a/src/ahriman/models/package.py b/src/ahriman/models/package.py
index 335a6864..0e80ed50 100644
--- a/src/ahriman/models/package.py
+++ b/src/ahriman/models/package.py
@@ -60,14 +60,18 @@ class Package:
     @property
     def depends(self) -> List[str]:
         """
+        get package base dependencies
+
         Returns:
-            List[str]: sum of dependencies per arch package
+            List[str]: sum of dependencies per each package
         """
         return sorted(set(sum([package.depends for package in self.packages.values()], start=[])))
 
     @property
     def git_url(self) -> str:
         """
+        get git clone url
+
         Returns:
             str: package git url to clone
         """
@@ -76,6 +80,8 @@ class Package:
     @property
     def groups(self) -> List[str]:
         """
+        get package base groups
+
         Returns:
             List[str]: sum of groups per each package
         """
@@ -84,6 +90,8 @@ class Package:
     @property
     def is_single_package(self) -> bool:
         """
+        is it possible to transform package base to single package or not
+
         Returns:
             bool: true in case if this base has only one package with the same name
         """
@@ -92,8 +100,10 @@ class Package:
     @property
     def is_vcs(self) -> bool:
         """
+        get VCS flag based on the package base
+
         Returns:
-            bool: True in case if package base looks like VCS package and false otherwise
+            bool: True in case if package base looks like VCS package and False otherwise
         """
         return self.base.endswith("-bzr") \
             or self.base.endswith("-csv")\
@@ -105,6 +115,8 @@ class Package:
     @property
     def licenses(self) -> List[str]:
         """
+        get package base licenses
+
         Returns:
             List[str]: sum of licenses per each package
         """
@@ -113,6 +125,8 @@ class Package:
     @property
     def web_url(self) -> str:
         """
+        get package url which can be used to see package in web
+
         Returns:
             str: package AUR url
         """
diff --git a/src/ahriman/models/package_description.py b/src/ahriman/models/package_description.py
index e8fd079b..534b6e68 100644
--- a/src/ahriman/models/package_description.py
+++ b/src/ahriman/models/package_description.py
@@ -61,6 +61,8 @@ class PackageDescription:
     @property
     def filepath(self) -> Optional[Path]:
         """
+        wrapper for filename, convert it to Path object
+
         Returns:
             Optional[Path]: path object for current filename
         """
diff --git a/src/ahriman/models/repository_paths.py b/src/ahriman/models/repository_paths.py
index 69536e65..7d5dc2e1 100644
--- a/src/ahriman/models/repository_paths.py
+++ b/src/ahriman/models/repository_paths.py
@@ -45,16 +45,20 @@ class RepositoryPaths:
     @property
     def cache(self) -> Path:
         """
+        get directory for packages cache (mainly used for VCS packages)
+
         Returns:
-            Path: directory for packages cache (mainly used for VCS packages)
+            Path: full path to cache directory
         """
         return self.root / "cache"
 
     @property
     def chroot(self) -> Path:
         """
+        get directory for devtools chroot
+
         Returns:
-            Path: directory for devtools chroot
+            Path: full patch to devtools chroot directory
         """
         # for the chroot directory devtools will create own tree, and we don"t have to specify architecture here
         return self.root / "chroot"
@@ -62,22 +66,28 @@ class RepositoryPaths:
     @property
     def packages(self) -> Path:
         """
+        get directory for built packages
+
         Returns:
-            Path: directory for built packages
+            Path: full path to built packages directory
         """
         return self.root / "packages" / self.architecture
 
     @property
     def repository(self) -> Path:
         """
+        get repository directory
+
         Returns:
-            Path: repository directory
+            Path: full path to the repository directory
         """
         return self.root / "repository" / self.architecture
 
     @property
     def root_owner(self) -> Tuple[int, int]:
         """
+        get UID and GID of the root directory
+
         Returns:
             Tuple[int, int]: owner user and group of the root directory
         """
diff --git a/src/ahriman/models/result.py b/src/ahriman/models/result.py
index fa9cb5fa..557f93a3 100644
--- a/src/ahriman/models/result.py
+++ b/src/ahriman/models/result.py
@@ -46,6 +46,8 @@ class Result:
     @property
     def failed(self) -> List[Package]:
         """
+        get list of failed packages
+
         Returns:
             List[Package]: list of packages which were failed
         """
@@ -54,6 +56,8 @@ class Result:
     @property
     def is_empty(self) -> bool:
         """
+        get if build result is empty or not
+
         Returns:
             bool: True in case if success list is empty and False otherwise
         """
@@ -62,6 +66,8 @@ class Result:
     @property
     def success(self) -> List[Package]:
         """
+        get list of success builds
+
         Returns:
             List[Package]: list of packages with success result
         """
diff --git a/src/ahriman/web/views/base.py b/src/ahriman/web/views/base.py
index 46757b43..1b29acf7 100644
--- a/src/ahriman/web/views/base.py
+++ b/src/ahriman/web/views/base.py
@@ -38,6 +38,8 @@ class BaseView(View):
     @property
     def configuration(self) -> Configuration:
         """
+        get configuration instance
+
         Returns:
             Configuration: configuration instance
         """
@@ -47,6 +49,8 @@ class BaseView(View):
     @property
     def database(self) -> SQLite:
         """
+        get database instance
+
         Returns:
             SQLite: database instance
         """
@@ -56,6 +60,8 @@ class BaseView(View):
     @property
     def service(self) -> Watcher:
         """
+        get status watcher instance
+
         Returns:
             Watcher: build status watcher instance
         """
@@ -65,6 +71,8 @@ class BaseView(View):
     @property
     def spawner(self) -> Spawn:
         """
+        get process spawner instance
+
         Returns:
             Spawn: external process spawner instance
         """
@@ -74,6 +82,8 @@ class BaseView(View):
     @property
     def validator(self) -> Auth:
         """
+        get authorization instance
+
         Returns:
             Auth: authorization service instance
         """