Examples sorting order fixed, theming scripts added to repository (#79)

* examples sorting order fixed, theming scripts added to repository * docs added for scripts * fix/theme_scripts_moved_from_unused_theme_to_project: rm dff_sphinx_theme * fix/theme_scripts_moved_from_unused_theme_to_project: upd dependencies * colab links added * github pages deployment action reverted * double titles removed * edit button removed from tutorial pages * edit button removed from tutorial pages * edit-this-page button removal test * unused files and lines removed * beautiful icon added * docs: add WiP in tutorials and development * change beautiful icon from png to svg * docs: update context storages * messengers added to examples, utils added to docs * sphinx build not distributed between cores anymore * utils docs removed * docs: minor fix --------- Co-authored-by: Denis Kuznetsov <[email protected]> Co-authored-by: avsakharov <[email protected]>
deeppavlov · Feb 19, 2023 · 2acc593 · 2acc593
1 parent 11eaea3
commit 2acc593
Show file tree

Hide file tree

Showing 24 changed files with 735 additions and 63 deletions.
diff --git a/.github/workflows/build_and_publish_docs.yml b/.github/workflows/build_and_publish_docs.yml
@@ -18,15 +18,9 @@ jobs:
   publish:
     name: build and publish docs
     runs-on: ubuntu-latest
-    permissions:
-      contents: 'read'
-      id-token: 'write'
     steps:
       - uses: actions/checkout@v2
 
-      - name: set up pages
-        uses: actions/configure-pages@v2
-
       - name: set up python 3.9
         uses: actions/setup-python@v2
         with:
@@ -65,12 +59,10 @@ jobs:
           path: docs/build/
           retention-days: 3
 
-      - name: upload artifact
+      - name: deploy website
         if: ${{ github.ref == 'refs/heads/dev' }}
-        uses: actions/upload-pages-artifact@v1
+        uses: JamesIves/github-pages-deploy-action@v4
         with:
-          path: docs/build/
-
-      - name: deploy to GitHub pages
-        if: ${{ github.ref == 'refs/heads/dev' }}
-        uses: actions/deploy-pages@v1
+          branch: gh-pages
+          folder: docs/build/
+          single-commit: True
diff --git a/dff/context_storages/database.py b/dff/context_storages/database.py
@@ -24,17 +24,13 @@ class DBContextStorage(ABC):
     It includes the most essential methods of the python `dict` class.
     Can not be instantiated.
 
-    Parameters
-    ----------
-    :param path:
-        | Parameter `path` should be set with the URI of the database.
-        | It includes a prefix and the required connection credentials.
-        | Example: postgresql+asyncpg://user:password@host:port/database
-        | In the case of classes that save data to hard drive instead of external databases
-        | you need to specify the location of the file, like you do in sqlite.
-        | Keep in mind that in Windows you will have to use double backslashes '\\'
-        | instead of forward slashes '/' when defining the file path.
-    :type path: str
+    :param path: Parameter `path` should be set with the URI of the database.
+        It includes a prefix and the required connection credentials.
+        Example: postgresql+asyncpg://user:password@host:port/database
+        In the case of classes that save data to hard drive instead of external databases
+        you need to specify the location of the file, like you do in sqlite.
+        Keep in mind that in Windows you will have to use double backslashes '\\'
+        instead of forward slashes '/' when defining the file path.
 
     """
 
@@ -50,8 +46,8 @@ def __init__(self, path: str):
     def __getitem__(self, key: Hashable) -> Context:
         """
         Synchronous method for accessing stored Context.
+
         :param key: Hashable key used to store Context instance.
-        :type key: Hashable
         :returns: The stored context, associated with the given key.
         """
         return asyncio.run(self.get_item_async(key))
@@ -60,55 +56,53 @@ def __getitem__(self, key: Hashable) -> Context:
     async def get_item_async(self, key: Hashable) -> Context:
         """
         Asynchronous method for accessing stored Context.
+
         :param key: Hashable key used to store Context instance.
-        :type key: Hashable
         :returns: The stored context, associated with the given key.
         """
         raise NotImplementedError
 
     def __setitem__(self, key: Hashable, value: Context):
         """
         Synchronous method for storing Context.
+
         :param key: Hashable key used to store Context instance.
-        :type key: Hashable
         :param value: Context to store.
-        :type value: Context
         """
         return asyncio.run(self.set_item_async(key, value))
 
     @abstractmethod
     async def set_item_async(self, key: Hashable, value: Context):
         """
         Asynchronous method for storing Context.
+
         :param key: Hashable key used to store Context instance.
-        :type key: Hashable
         :param value: Context to store.
-        :type value: Context
         """
         raise NotImplementedError
 
     def __delitem__(self, key: Hashable):
         """
         Synchronous method for removing stored Context.
+
         :param key: Hashable key used to identify Context instance for deletion.
-        :type key: Hashable
         """
         return asyncio.run(self.del_item_async(key))
 
     @abstractmethod
     async def del_item_async(self, key: Hashable):
         """
         Asynchronous method for removing stored Context.
+
         :param key: Hashable key used to identify Context instance for deletion.
-        :type key: Hashable
         """
         raise NotImplementedError
 
     def __contains__(self, key: Hashable) -> bool:
         """
         Synchronous method for finding whether any Context is stored with given key.
+
         :param key: Hashable key used to check if Context instance is stored.
-        :type key: Hashable
         :returns: True if there is Context accessible by given key, False otherwise.
         """
         return asyncio.run(self.contains_async(key))
@@ -117,15 +111,16 @@ def __contains__(self, key: Hashable) -> bool:
     async def contains_async(self, key: Hashable) -> bool:
         """
         Asynchronous method for finding whether any Context is stored with given key.
+
         :param key: Hashable key used to check if Context instance is stored.
-        :type key: Hashable
         :returns: True if there is Context accessible by given key, False otherwise.
         """
         raise NotImplementedError
 
     def __len__(self) -> int:
         """
         Synchronous method for retrieving number of stored Contexts.
+
         :returns: The number of stored Contexts.
         """
         return asyncio.run(self.len_async())
@@ -134,28 +129,27 @@ def __len__(self) -> int:
     async def len_async(self) -> int:
         """
         Asynchronous method for retrieving number of stored Contexts.
+
         :returns: The number of stored Contexts.
         """
         raise NotImplementedError
 
     def get(self, key: Hashable, default: Optional[Context] = None) -> Context:
         """
         Synchronous method for accessing stored Context, returning default if no Context is stored with the given key.
+
         :param key: Hashable key used to store Context instance.
-        :type key: Hashable
         :param default: Optional default value to be returned if no Context is found.
-        :type key: Optional[Context]
         :returns: The stored context, associated with the given key or default value.
         """
         return asyncio.run(self.get_async(key, default))
 
     async def get_async(self, key: Hashable, default: Optional[Context] = None) -> Context:
         """
         Asynchronous method for accessing stored Context, returning default if no Context is stored with the given key.
+
         :param key: Hashable key used to store Context instance.
-        :type key: Hashable
         :param default: Optional default value to be returned if no Context is found.
-        :type key: Optional[Context]
         :returns: The stored context, associated with the given key or default value.
         """
         try:
@@ -195,8 +189,10 @@ def context_storage_factory(path: str, **kwargs) -> DBContextStorage:
     Use context_storage_factory to lazy import context storage types and instantiate them.
     The function takes a database connection URI or its equivalent. It should be prefixed with database name,
     followed by the symbol triplet '://'.
+
     Then, you should list the connection parameters like this: user:password@host:port/database
     The whole URI will then look like this:
+
     - shelve://path_to_the_file/file_name
     - json://path_to_the_file/file_name
     - pickle://path_to_the_file/file_name
@@ -210,10 +206,11 @@ def context_storage_factory(path: str, **kwargs) -> DBContextStorage:
 
     For context storages that write to local files, the function expects a file path instead of connection params:
     json://file.json
-    When using sqlite backend your prefix should contain three slashes if you use Windows, or four in other cases.
+    When using sqlite backend your prefix should contain three slashes if you use Windows, or four in other cases:
     sqlite:////file.db
     If you want to use additional parameters in class constructors, you can pass them to this function as kwargs.
 
+    :param path: Path to the file.
     """
     prefix, _, _ = path.partition("://")
     if "sql" in prefix:

diff --git a/dff/context_storages/json.py b/dff/context_storages/json.py
@@ -1,6 +1,6 @@
 """
 JSON
------
+----
 The JSON module provides a json-based version of the :py:class:`.DBContextStorage` class.
 This class is used to store and retrieve context data in a JSON. It allows the `DFF` to easily
 store and retrieve context data.

diff --git a/dff/context_storages/mongo.py b/dff/context_storages/mongo.py
@@ -34,9 +34,7 @@ class MongoContextStorage(DBContextStorage):
     Implements :py:class:`.DBContextStorage` with `mongodb` as the database backend.
 
     :param path: Database URI. Example: `mongodb://user:password@host:port/dbname`.
-    :type path: str
     :param collection: Name of the collection to store the data in.
-    :type collection: str
     """
 
     def __init__(self, path: str, collection: str = "context_collection"):

diff --git a/dff/context_storages/pickle.py b/dff/context_storages/pickle.py
@@ -31,7 +31,6 @@ class PickleContextStorage(DBContextStorage):
     Implements :py:class:`.DBContextStorage` with `pickle` as driver.
 
     :param path: Target file URI. Example: 'pickle://file.pkl'.
-    :type path: str
     """
 
     def __init__(self, path: str):

diff --git a/dff/context_storages/shelve.py b/dff/context_storages/shelve.py
@@ -26,7 +26,6 @@ class ShelveContextStorage(DBContextStorage):
     Implements :py:class:`.DBContextStorage` with `shelve` as the driver.
 
     :param path: Target file URI. Example: `shelve://file.db`.
-    :type path: str
     """
 
     def __init__(self, path: str):

diff --git a/dff/context_storages/sql.py b/dff/context_storages/sql.py
@@ -66,6 +66,8 @@
 def import_insert_for_dialect(dialect: str):
     """
     Imports the insert function into global scope depending on the chosen sqlalchemy dialect.
+
+    :param dialect: Chosen sqlalchemy dialect.
     """
     global insert
     insert = getattr(
@@ -82,12 +84,9 @@ class SQLContextStorage(DBContextStorage):
     :param path: Standard sqlalchemy URI string.
         When using sqlite backend in Windows, keep in mind that you have to use double backslashes '\\'
         instead of forward slashes '/' in the file path.
-    :type path: str
     :param table_name: The name of the table to use.
-    :type table_name: str
     :param custom_driver: If you intend to use some other database driver instead of the recommended ones,
         set this parameter to `True` to bypass the import checks.
-    :type custom_driver: bool
     """
 
     def __init__(self, path: str, table_name: str = "contexts", custom_driver: bool = False):

diff --git a/dff/context_storages/ydb.py b/dff/context_storages/ydb.py
@@ -31,12 +31,11 @@
 
 class YDBContextStorage(DBContextStorage):
     """
-    | Version of the :py:class:`.DBContextStorage` for YDB.
+    Version of the :py:class:`.DBContextStorage` for YDB.
 
-        :param path: Standard sqlalchemy URI string.
+    :param path: Standard sqlalchemy URI string.
         When using sqlite backend in Windows, keep in mind that you have to use double backslashes '\\'
         instead of forward slashes '/' in the file path.
-    :type path: str
     :param table_name: The name of the table to use.
     :type table_name: str
     """

diff --git a/dff/messengers/common/interface.py b/dff/messengers/common/interface.py
@@ -31,6 +31,7 @@ async def connect(self, pipeline_runner: PipelineRunnerFunction):
 
         :param pipeline_runner: A function that should return pipeline response to user request;
             usually it's a :py:meth:`~Pipeline._run_pipeline(request, ctx_id)` function.
+        :type pipeline_runner: PipelineRunnerFunction
         """
         raise NotImplementedError
 
@@ -97,8 +98,10 @@ async def connect(
 
         :param pipeline_runner: A function that should return pipeline response to user request;
             usually it's a :py:meth:`~Pipeline._run_pipeline(request, ctx_id)` function.
+        :type pipeline_runner: PipelineRunnerFunction
         :param loop: a function that determines whether polling should be continued;
             called in each cycle, should return `True` to continue polling or `False` to stop.
+        :type loop: PollingInterfaceLoopFunction
         :param timeout: a time interval between polls (in seconds).
         """
         while loop():
@@ -123,8 +126,7 @@ async def connect(self, pipeline_runner: PipelineRunnerFunction):
 
     def on_request(self, request: Any, ctx_id: Hashable) -> Context:
         """
-        Method invoked on user input.
-        This method works just like :py:meth:`~Pipeline.__call__(request, ctx_id)`,
+        Method invoked on user input. This method works just like :py:meth:`.__call__(request, ctx_id)`,
         however callback message interface may contain additional functionality (e.g. for external API accessing).
         Returns context that represents dialog with the user;
         `last_response`, `id` and some dialog info can be extracted from there.
@@ -168,6 +170,7 @@ async def connect(self, pipeline_runner: PipelineRunnerFunction, **kwargs):
 
         :param pipeline_runner: A function that should return pipeline response to user request;
             usually it's a :py:meth:`~Pipeline._run_pipeline(request, ctx_id)` function.
+        :type pipeline_runner: PipelineRunnerFunction
         :param \\**kwargs: argument, added for compatibility with super class, it shouldn't be used normally.
         """
         self._ctx_id = uuid.uuid4()

diff --git a/docs/source/_static/css/custom.css b/docs/source/_static/css/custom.css
@@ -0,0 +1,45 @@
+.call-to-action-any {
+    width: 2rem;
+    height: 2rem;
+    margin-inline-end: 10px;
+    background-size: 100% 100%;
+}
+
+.pytorch-colab {
+    background-image: url("../images/logo-colab.svg");
+}
+
+.pytorch-download {
+    background-image: url("../images/logo-download.svg");
+}
+
+.pytorch-github {
+    background-image: url("../images/logo-github.svg");
+}
+
+
+
+.call-to-action-desktop-view {
+    display: none;
+}
+
+.call-to-action-mobile-view {
+    display: block;
+}
+
+#google-colab-link, #download-notebook-link, #github-view-link {
+    padding-bottom: 0.625rem;
+    display: flex;
+}
+
+
+
+@media screen and (min-width: 768px) {
+    .call-to-action-desktop-view {
+        display: block;
+    }
+
+    .call-to-action-mobile-view {
+        display: none;
+    }
+}
diff --git a/docs/source/_static/images/logo-colab.svg b/docs/source/_static/images/logo-colab.svg