Merge branch 'master' into feature/config-disable-auth

.gitignore

@@ -110,5 +110,8 @@ ENV/
 etc/site.conf
 etc/site.d/
 
-doc/_build
 examples/ssl/clients/.index.bin
+
+# mkdocs
+doc/_build
+doc/env

.gitlab-ci.yml

@@ -0,0 +1,46 @@
+stages:
+  - deploy
+
+deploy staging:
+  stage: deploy
+  tags:
+    - docker
+  image: 
+    name: squidfunk/mkdocs-material
+    entrypoint: [""]
+  script:
+    - apk update && apk add openssh-client rsync
+    - pip3 install mkdocs-print-site-plugin mkdocs-awesome-pages-plugin mkdocs-glightbox mkdocstrings mkdocstrings[python] mkdocs-git-revision-date-localized-plugin
+    - mkdir -p ~/.ssh
+    - echo "$DEPLOY_PRIVATE_KEY" > ~/.ssh/id_rsa
+    - chmod 600 ~/.ssh/id_rsa
+    - echo -e "Host *\n\tStrictHostKeyChecking no\n\n" > ~/.ssh/config
+    - mkdir /output
+    - mkdocs build --site-dir /output
+    # For other languages
+    # - (cd ./cs && mkdocs build --site-dir /output/cs)
+    - rsync -r -a -v -e ssh --delete /output/ "$RSYNC_USER"@"$TARGET_SERVER":"$STAGING_DIR"
+  only:
+    - master
+
+deploy production:
+  stage: deploy
+  tags:
+    - docker
+  image: 
+    name: squidfunk/mkdocs-material
+    entrypoint: [""]
+  script:
+    - apk update && apk add openssh-client rsync
+    - pip3 install mkdocs-print-site-plugin mkdocs-awesome-pages-plugin mkdocs-glightbox mkdocstrings mkdocstrings[python] mkdocs-git-revision-date-localized-plugin
+    - mkdir -p ~/.ssh
+    - echo "$DEPLOY_PRIVATE_KEY" > ~/.ssh/id_rsa
+    - chmod 600 ~/.ssh/id_rsa
+    - echo -e "Host *\n\tStrictHostKeyChecking no\n\n" > ~/.ssh/config
+    - mkdir /output
+    - mkdocs build --site-dir /output
+    # For other languages
+    # - (cd ./cs && mkdocs build --site-dir /output/cs)
+    - rsync -r -a -v -e ssh --delete /output/ "$RSYNC_USER"@"$TARGET_SERVER":"$PRODUCTION_DIR"
+  only:
+    - production

asab/__init__.py

@@ -1,3 +1,14 @@
+"""Asynchronous Server Application Boilerplate.
+
+ASAB (Asynchronous Serverless Application Builder) is a lightweight Python framework for building
+asynchronous and serverless applications. It provides a simple yet powerful set of tools and
+conventions for developing scalable and efficient applications.
+
+For detailed documentation and examples, please refer to the ASAB documentation at:
+	- GitHub Repository: https://github.com/TeskaLabs/asab
+	- Documentation: https://asab.readthedocs.io
+"""
+
 import logging
 
 from .abc.module import Module

asab/abc/module.py

@@ -3,7 +3,52 @@
 
 class Module(abc.ABC):
 	"""
-	Abstract module class
+	Abstract class for ASAB modules.
+
+	Modules are registered at the module registry `asab.Application.Modules`, managed by an application object.
+	Module can be loaded by ASAB and typically provides one or more Service objects.
+
+	Every module provides asynchronous methods `initialize()` and `finalize()`.
+	`initialize()` is called in the very beginning of the run-time,
+	`finalize()` in the gentle shut-down of the application.
+
+	Examples:
+
+	Recommended structure of the ASAB module:
+
+	```
+	my_module/
+		- __init__.py
+		- my_service.py
+	```
+
+	Content of `__init__.py`:
+
+	```python title="__init__.py"
+	import asab
+	from .my_service import MyService
+
+	# Extend ASAB configuration defaults
+	asab.Config.add_defaults({
+		'my_module': {
+			'foo': 'bar'
+		}
+	})
+
+	class MyModule(asab.Module):
+		def __init__(self, app):
+			super().__init__(app)
+			self.service = MyService(app, "MyService")
+	```
+
+	And this is how the module is loaded:
+
+	```python
+	from mymodule import MyModule
+	...
+	app.add_module(MyModule)
+	```
+
 	"""
 
 	def __init__(self, app):
@@ -12,7 +57,19 @@ def __init__(self, app):
 	# Lifecycle
 
 	async def initialize(self, app):
+		"""
+		This method is called when the Module is initialized. It can be overridden by an user.
+
+		Args:
+			app (asab.Application): Reference to ASAB application.
+		"""
 		pass
 
 	async def finalize(self, app):
+		"""
+		This method is called when the Module is finalized, e.g., during application `exit-time`. It can be overridden by an user.
+
+		Args:
+			app (asab.Application): Reference to ASAB application.
+		"""
 		pass

asab/abc/service.py

@@ -3,18 +3,79 @@
 
 class Service(abc.ABC):
 	"""
-	Abstract service class
+	Abstract class for ASAB services.
+
+	Service objects are registered at the service registry `asab.Application.Services`, managed by an application object.
+
+	Examples:
+
+	This is how Service is created and registered:
+	```python
+	my_service = MyService(app, "my_service")
+	```
+
+	This is how Service is located and used:
+
+	```python
+	my_service = app.get_service("my_service")
+	my_service.service_method()
+	```
+
+	Example of a typical Service class skeleton:
+
+	```python
+	class MyService(asab.Service):
+		def __init__(self, app, service_name):
+			super().__init__(app, service_name)
+			...
+
+		async def initialize(self, app):
+			...
+
+		async def finalize(self, app):
+			...
+
+		def service_method(self):
+			...
+	```
 	"""
 
-	def __init__(self, app, service_name):
+	def __init__(self, app, service_name: str):
+		"""
+		Register the service to `asab.Application.Services` dictionary with the provided `service_name`.
+
+		Args:
+			app (asab.Application): Reference to ASAB application.
+			service_name: Reference name of the Service.
+		"""
 		self.Name = service_name
+		"""
+		The reference name for the Service.
+		"""
 		self.App = app
+		"""
+		The reference to the Application object.
+		"""
 		app._register_service(self)
 
 	# Lifecycle
 
 	async def initialize(self, app):
+		"""
+		This method is called when the Service is initialized.
+		It can be overridden by an user.
+
+		Args:
+			app (asab.Application): Reference to ASAB application.
+		"""
 		pass
 
 	async def finalize(self, app):
+		"""
+		This method is called when the Service is finalized, e.g., during application `exit-time`.
+		It can be overridden by an user.
+
+		Args:
+			app (asab.Application): Reference to ASAB application.
+		"""
 		pass