Add documentation site (#52)

.github/workflows/deploy-docs.yml

@@ -0,0 +1,36 @@
+name: Deploy docs
+on:
+  push:
+    branches:
+      - master
+      - main
+    paths:
+      - '.github/workflows/deploy-docs.yml'
+      - 'pyproject.toml'
+      - 'poetry.lock'
+      - 'mkdocs.yml'
+      - 'docs/*'
+      - 'async-tkinter-loop/*'
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Install poetry
+        run: pipx install poetry
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+
+      - name: Install dependencies
+        run: poetry install --only docs
+
+      - name: Deploy docs
+        run: poetry run mkdocs gh-deploy --force

.github/workflows/python-tests.yml

@@ -39,7 +39,7 @@ jobs:
         cache-dependency-path: poetry.lock
 
     - name: Install dependencies
-      run: poetry install
+      run: poetry install --without docs
 
     - name: Lint with flake8
       run: |

async_tkinter_loop/async_tkinter_loop.py

@@ -1,17 +1,19 @@
+import _tkinter
 import asyncio
 import tkinter
 from functools import wraps
-from tkinter import TclError
 from typing import Any, Callable, Coroutine
 
-import _tkinter
+from tkinter import TclError
 
 
 async def main_loop(root: tkinter.Tk) -> None:
     """
-    An asynchronous implementation of tkinter mainloop
-    :param root: tkinter root object
-    :return: nothing
+    An asynchronous implementation of tkinter mainloop.
+    The function is not intended to be called directly from your code.
+
+    Args:
+        root: tkinter root window object
     """
     while True:
         # Process all pending events
@@ -28,58 +30,68 @@ async def main_loop(root: tkinter.Tk) -> None:
 
 def get_event_loop() -> asyncio.AbstractEventLoop:
     """
-    A helper function to get event loop using current event loop policy
-    :return: event loop
+    A helper function which returns an event loop using current event loop policy.
+
+    Returns:
+        event loop
     """
     return asyncio.get_event_loop_policy().get_event_loop()
 
 
 def async_mainloop(root: tkinter.Tk) -> None:
     """
-    A synchronous function to run asynchronous main_loop function
-    :param root: tkinter root object
-    :return: nothing
+    A function, which is a substitute to the standard `root.mainloop()`.
+
+    Args:
+        root: tkinter root object
     """
     get_event_loop().run_until_complete(main_loop(root))
 
 
 def async_handler(async_function: Callable[..., Coroutine[Any, Any, None]], *args, **kwargs) -> Callable[..., None]:
     """
-    Helper function to pass async functions as command handlers (e.g. button click handlers) or event handlers
+    A helper function which allows to use async functions as command handlers (e.g. button click handlers) or event
+    handlers.
+
+    Args:
+        async_function: async function
+        args: positional parameters which will be passed to the async function
+        kwargs: keyword parameters which will be passed to the async function
 
-    :param async_function: async function
-    :param args: positional parameters which will be passed to the async function
-    :param kwargs: keyword parameters which will be passed to the async function
-    :return: function
+    Returns:
+        A sync function, which runs the original async function in an async event loop.
 
-    Examples: ::
+    Usage examples:
+    ```python
+    from async_tkinter_loop import async_handler
 
-        async def some_async_function():
-            print("Wait...")
-            await asyncio.sleep(0.5)
-            print("Done!")
+    async def some_async_function():
+        print("Wait...")
+        await asyncio.sleep(0.5)
+        print("Done!")
 
-        button = tk.Button("Press me", command=async_handler(some_async_function))
+    button = tk.Button("Press me", command=async_handler(some_async_function))
 
-        # ----
+    # ----
 
-        async def some_async_function(event):
-            print("Wait...")
-            await asyncio.sleep(0.5)
-            print("Done!")
+    async def some_async_function(event):
+        print("Wait...")
+        await asyncio.sleep(0.5)
+        print("Done!")
 
-        root.bind("<1>", command=async_handler(some_async_function))
+    root.bind("<1>", command=async_handler(some_async_function))
 
-        # ----
+    # ----
 
-        # Also, it can be used as a decorator
-        @async_handler
-        async def some_async_function():
-            print("Wait...")
-            await asyncio.sleep(0.5)
-            print("Done!")
+    # Also, it can be used as a decorator
+    @async_handler
+    async def some_async_function():
+        print("Wait...")
+        await asyncio.sleep(0.5)
+        print("Done!")
 
-        button = tk.Button("Press me", command=some_async_function)
+    button = tk.Button("Press me", command=some_async_function)
+    ```
     """
 
     @wraps(async_function)

docs/api.md

@@ -0,0 +1,3 @@
+# Library API
+
+:::async_tkinter_loop.async_tkinter_loop

docs/index.md

@@ -0,0 +1,4 @@
+# Welcome
+
+This site contains the project documentation for the
+`async-tkinter-loop` project.

docs/similar_projects.md

@@ -1,13 +1,13 @@
 # Similar projects
 
 * [Starwort/asynctk](https://github.com/Starwort/asynctk) ([on PyPi](https://pypi.org/project/asynctk/)) - tries to wrap all widgets and make all their methods asyncroneous.  
-   Most recent commit: Oct 31, 2021.  
+   Most recent commit: October 2021.  
    GPL v3 license.
-* [gottadiveintopython/asynctkinter](https://github.com/gottadiveintopython/asynctkinter) ([on PyPi](https://pypi.org/project/asynctkinter/)) - looks like an asyncroneous framework itself (like [trio](https://github.com/python-trio/trio)).  
-   Most recent commit: Sep 20, 2022.  
+* [gottadiveintopython/asynctkinter](https://github.com/gottadiveintopython/asynctkinter) ([on PyPi](https://pypi.org/project/asynctkinter/)) - looks like an asynchronous framework itself (like [trio](https://github.com/python-trio/trio)).  
+   Most recent commit: August 2023.  
    MIT License.
 
-The latter two projects use old `asyncio` code (from before `async`/`await` keyword addition):
+The latter two projects use old `asyncio` code (from before `async`/`await` syntax addition):
 
 * [Lucretiel/tkinter-async](https://github.com/Lucretiel/tkinter-async) - most recent commit: May 7, 2015
 * [fluentpython/asyncio-tkinter](https://github.com/fluentpython/asyncio-tkinter) - most recent commit: Apr 5, 2015.

mkdocs.yml

@@ -0,0 +1,7 @@
+site_name: Async-tkinter-loop documentation
+
+theme:
+  name: "material"
+
+plugins:
+  - mkdocstrings