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

@@ -21,12 +21,16 @@ _request = namedtuple("_request", ["app", "path", "method", "json", "post"])
 def request(app: web.Application, path: str, method: str, json: Any = None, data: Any = None) -> _request:
     """
     request generator helper
-    :param app: application fixture
-    :param path: path for the request
-    :param method: method for the request
-    :param json: json payload of the request
-    :param data: form data payload of the request
-    :return: dummy request object
+
+    Args:
+        app(web.Application): application fixture
+        path(str): path for the request
+        method(str): method for the request
+        json(Any, optional): json payload of the request (Default value = None)
+        data(Any, optional): form data payload of the request (Default value = None)
+
+    Returns:
+        _request: dummy request object
     """
     return _request(app, path, method, json, data)
 
@@ -36,11 +40,15 @@ def application(configuration: Configuration, spawner: Spawn, database: SQLite,
                 mocker: MockerFixture) -> web.Application:
     """
     application fixture
-    :param configuration: configuration fixture
-    :param spawner: spawner fixture
-    :param database: database fixture
-    :param mocker: mocker object
-    :return: application test instance
+
+    Args:
+        configuration(Configuration): configuration fixture
+        spawner(Spawn): spawner fixture
+        database(SQLite): database fixture
+        mocker(MockerFixture): mocker object
+
+    Returns:
+        web.Application: application test instance
     """
     mocker.patch("ahriman.core.database.sqlite.SQLite.load", return_value=database)
     mocker.patch("ahriman.models.repository_paths.RepositoryPaths.tree_create")
@@ -53,12 +61,16 @@ def application_with_auth(configuration: Configuration, user: User, spawner: Spa
                           mocker: MockerFixture) -> web.Application:
     """
     application fixture with auth enabled
-    :param configuration: configuration fixture
-    :param user: user descriptor fixture
-    :param spawner: spawner fixture
-    :param database: database fixture
-    :param mocker: mocker object
-    :return: application test instance
+
+    Args:
+        configuration(Configuration): configuration fixture
+        user(User): user descriptor fixture
+        spawner(Spawn): spawner fixture
+        database(SQLite): database fixture
+        mocker(MockerFixture): mocker object
+
+    Returns:
+        web.Application: application test instance
     """
     configuration.set_option("auth", "target", "configuration")
     mocker.patch("ahriman.core.database.sqlite.SQLite.load", return_value=database)
@@ -77,12 +89,16 @@ def application_with_debug(configuration: Configuration, user: User, spawner: Sp
                            mocker: MockerFixture) -> web.Application:
     """
     application fixture with debug enabled
-    :param configuration: configuration fixture
-    :param user: user descriptor fixture
-    :param spawner: spawner fixture
-    :param database: database fixture
-    :param mocker: mocker object
-    :return: application test instance
+
+    Args:
+        configuration(Configuration): configuration fixture
+        user(User): user descriptor fixture
+        spawner(Spawn): spawner fixture
+        database(SQLite): database fixture
+        mocker(MockerFixture): mocker object
+
+    Returns:
+        web.Application: application test instance
     """
     configuration.set_option("web", "debug", "yes")
     mocker.patch("ahriman.core.database.sqlite.SQLite.load", return_value=database)

tests/ahriman/web/middlewares/conftest.py

@@ -11,7 +11,14 @@ from ahriman.web.middlewares.auth_handler import AuthorizationPolicy
 def authorization_policy(configuration: Configuration, database: SQLite, user: User) -> AuthorizationPolicy:
     """
     fixture for authorization policy
-    :return: authorization policy fixture
+
+    Args:
+        configuration(Configuration): configuration fixture
+        database(SQLite): database fixture
+        user(User): user fixture
+
+    Returns:
+        AuthorizationPolicy: authorization policy fixture
     """
     configuration.set_option("auth", "target", "configuration")
     validator = Auth.load(configuration, database)

tests/ahriman/web/middlewares/test_auth_handler.py

@@ -14,8 +14,12 @@ from ahriman.web.middlewares.auth_handler import auth_handler, AuthorizationPoli
 def _identity(username: str) -> str:
     """
     generate identity from user
-    :param username: name of the user
-    :return: user identity string
+
+    Args:
+        username(str): name of the user
+
+    Returns:
+        str: user identity string
     """
     return f"{username} {UserIdentity.expire_when(60)}"
 

tests/ahriman/web/middlewares/test_exception_handler.py

@@ -13,8 +13,12 @@ from ahriman.web.middlewares.exception_handler import exception_handler
 def _extract_body(response: Any) -> Any:
     """
     extract json body from given object
-    :param response: response (any actually) object
-    :return: body key from the object converted to json
+
+    Args:
+        response(Any): response (any actually) object
+
+    Returns:
+        Any: body key from the object converted to json
     """
     return json.loads(getattr(response, "body"))
 

tests/ahriman/web/views/conftest.py

@@ -15,8 +15,12 @@ from ahriman.web.views.base import BaseView
 def base(application: web.Application) -> BaseView:
     """
     base view fixture
-    :param application: application fixture
-    :return: generated base view fixture
+
+    Args:
+        application(web.Application): application fixture
+
+    Returns:
+        BaseView: generated base view fixture
     """
     return BaseView(pytest.helpers.request(application, "", ""))
 
@@ -26,11 +30,15 @@ def client(application: web.Application, event_loop: BaseEventLoop,
            aiohttp_client: Any, mocker: MockerFixture) -> TestClient:
     """
     web client fixture
-    :param application: application fixture
-    :param event_loop: context event loop
-    :param aiohttp_client: aiohttp client fixture
-    :param mocker: mocker object
-    :return: web client test instance
+
+    Args:
+        application(web.Application): application fixture
+        event_loop(BaseEventLoop): context event loop
+        aiohttp_client(Any): aiohttp client fixture
+        mocker(MockerFixture): mocker object
+
+    Returns:
+        TestClient: web client test instance
     """
     mocker.patch("pathlib.Path.iterdir", return_value=[])
     return event_loop.run_until_complete(aiohttp_client(application))
@@ -41,11 +49,15 @@ def client_with_auth(application_with_auth: web.Application, event_loop: BaseEve
                      aiohttp_client: Any, mocker: MockerFixture) -> TestClient:
     """
     web client fixture with full authorization functions
-    :param application_with_auth: application fixture
-    :param event_loop: context event loop
-    :param aiohttp_client: aiohttp client fixture
-    :param mocker: mocker object
-    :return: web client test instance
+
+    Args:
+        application_with_auth(web.Application): application fixture
+        event_loop(BaseEventLoop): context event loop
+        aiohttp_client(Any): aiohttp client fixture
+        mocker(MockerFixture): mocker object
+
+    Returns:
+        TestClient: web client test instance
     """
     mocker.patch("pathlib.Path.iterdir", return_value=[])
     return event_loop.run_until_complete(aiohttp_client(application_with_auth))
@@ -56,11 +68,15 @@ def client_with_oauth_auth(application_with_auth: web.Application, event_loop: B
                            aiohttp_client: Any, mocker: MockerFixture) -> TestClient:
     """
     web client fixture with full authorization functions
-    :param application_with_auth: application fixture
-    :param event_loop: context event loop
-    :param aiohttp_client: aiohttp client fixture
-    :param mocker: mocker object
-    :return: web client test instance
+
+    Args:
+        application_with_auth(web.Application): application fixture
+        event_loop(BaseEventLoop): context event loop
+        aiohttp_client(Any): aiohttp client fixture
+        mocker(MockerFixture): mocker object
+
+    Returns:
+        TestClient: web client test instance
     """
     mocker.patch("pathlib.Path.iterdir", return_value=[])
     application_with_auth["validator"] = MagicMock(spec=OAuth)