WIP: Documentation improvement and format change to Google

src/libbot/utils/config/_functions.py

@@ -15,34 +15,24 @@ DEFAULT_CONFIG_LOCATION: str = "config.json"
 
 @asyncable
 def config_get(key: str, *path: str, config_file: str | Path = DEFAULT_CONFIG_LOCATION) -> Any:
-    """Get a value of the config key by its path provided
-    For example, `foo.bar.key` has a path of `"foo", "bar"` and the key `"key"`
+    """Get a value of the config key by its path provided.
+    For example, `foo.bar.key` has a path of `"foo", "bar"` and the key `"key"`.
 
-    ### Args:
-        * key (`str`): Key that contains the value
-        * *path (`str`): Path to the key that contains the value (pass *[] or don't pass anything at all to get on the top/root level)
-        * config_file (`str | Path`, *optional*): Path-like object or path as a string of a location of the config file. Defaults to `"config.json"`
+    Args:
+        key (str): Key that contains the value
+        *path (str): Path to the key that contains the value (pass *[] or don't pass anything at all to get on the top/root level)
+        config_file (str | Path, optional): Path-like object or path as a string of a location of the config file. Defaults to `"config.json"`
 
-    ### Returns:
-        * `Any`: Key's value
+    Returns:
+        Any: Key's value
 
-    ### Example:
-    Get the "salary" of "Pete" from this JSON structure:
-    ```json
-    {
-        "users": {
-            "Pete": {
-                "salary": 10.0
-            }
-        }
-    }
-    ```
+    Example:
+        Get the "salary" of "Pete" from this JSON structure: `{"users": {"Pete": {"salary": 10.0}}}`
 
-    This can be easily done with the following code:
-    ```python
-    import libbot
-    salary = libbot.sync.config_get("salary", "users", "Pete")
-    ```
+        This can be easily done with the following code:
+
+        >>> import libbot
+        salary: float = libbot.sync.config_get("salary", "users", "Pete")
     """
     this_key: Dict[str, Any] = json_read(config_file)
 
@@ -54,34 +44,24 @@ def config_get(key: str, *path: str, config_file: str | Path = DEFAULT_CONFIG_LO
 
 @config_get.asynchronous
 async def config_get(key: str, *path: str, config_file: str | Path = DEFAULT_CONFIG_LOCATION) -> Any:
-    """Get a value of the config key by its path provided
-    For example, `foo.bar.key` has a path of `"foo", "bar"` and the key `"key"`
+    """Get a value of the config key by its path provided.
+    For example, `foo.bar.key` has a path of `"foo", "bar"` and the key `"key"`.
 
-    ### Args:
-        * key (`str`): Key that contains the value
-        * *path (`str`): Path to the key that contains the value (pass *[] or don't pass anything at all to get on the top/root level)
-        * config_file (`str | Path`, *optional*): Path-like object or path as a string of a location of the config file. Defaults to `"config.json"`
+    Args:
+        key (str): Key that contains the value
+        *path (str): Path to the key that contains the value (pass *[] or don't pass anything at all to get on the top/root level)
+        config_file (str | Path, optional): Path-like object or path as a string of a location of the config file. Defaults to `"config.json"`
 
-    ### Returns:
-        * `Any`: Key's value
+    Returns:
+        Any: Key's value
 
-    ### Example:
-    Get the "salary" of "Pete" from this JSON structure:
-    ```json
-    {
-        "users": {
-            "Pete": {
-                "salary": 10.0
-            }
-        }
-    }
-    ```
+    Example:
+        Get the "salary" of "Pete" from this JSON structure: `{"users": {"Pete": {"salary": 10.0}}}`
 
-    This can be easily done with the following code:
-    ```python
-    import libbot
-    salary = await libbot.config_get("salary", "users", "Pete")
-    ```
+        This can be easily done with the following code:
+
+        >>> import libbot
+        salary: float = libbot.sync.config_get("salary", "users", "Pete")
     """
     this_key: Dict[str, Any] = await json_read(config_file)
 
@@ -93,16 +73,16 @@ async def config_get(key: str, *path: str, config_file: str | Path = DEFAULT_CON
 
 @asyncable
 def config_set(key: str, value: Any, *path: str, config_file: str | Path = DEFAULT_CONFIG_LOCATION) -> None:
-    """Set config's key by its path to the value
+    """Set config's key by its path to the value.
 
-    ### Args:
-        * key (`str`): Key that leads to the value
-        * value (`Any`): Any JSON serializable data
-        * *path (`str`): Path to the key of the target (pass *[] or don't pass anything at all to set on the top/root level)
-        * config_file (`str | Path`, *optional*): Path-like object or path as a string of a location of the config file. Defaults to `"config.json"`
+    Args:
+        key (str): Key that leads to the value.
+        value (Any): Any JSON-serializable data.
+        *path (str): Path to the key of the target (pass *[] or don't pass anything at all to set on the top/root level).
+        config_file (str | Path, optional): Path-like object or path as a string of a location of the config file. Defaults to "config.json".
 
-    ### Raises:
-        * `KeyError`: Key is not found under path provided
+    Raises:
+        KeyError: Key was not found under the provided path.
     """
     json_write(nested_set(json_read(config_file), value, *(*path, key)), config_file)
 
@@ -111,16 +91,16 @@ def config_set(key: str, value: Any, *path: str, config_file: str | Path = DEFAU
 async def config_set(
     key: str, value: Any, *path: str, config_file: str | Path = DEFAULT_CONFIG_LOCATION
 ) -> None:
-    """Set config's key by its path to the value
+    """Set config's key by its path to the value.
 
-    ### Args:
-        * key (`str`): Key that leads to the value
-        * value (`Any`): Any JSON serializable data
-        * *path (`str`): Path to the key of the target (pass *[] or don't pass anything at all to set on the top/root level)
-        * config_file (`str | Path`, *optional*): Path-like object or path as a string of a location of the config file. Defaults to `"config.json"`
+    Args:
+        key (str): Key that leads to the value.
+        value (Any): Any JSON-serializable data.
+        *path (str): Path to the key of the target (pass *[] or don't pass anything at all to set on the top/root level).
+        config_file (str | Path, optional): Path-like object or path as a string of a location of the config file. Defaults to "config.json".
 
-    ### Raises:
-        * `KeyError`: Key is not found under path provided
+    Raises:
+        KeyError: Key was not found under the provided path.
     """
     await json_write(nested_set(await json_read(config_file), value, *(*path, key)), config_file)
 
@@ -132,16 +112,16 @@ def config_delete(
     missing_ok: bool = False,
     config_file: str | Path = DEFAULT_CONFIG_LOCATION,
 ) -> None:
-    """Set config's key by its path
+    """Delete config's key by its path.
 
-    ### Args:
-        * key (`str`): Key to delete
-        * *path (`str`): Path to the key of the target (pass *[] or don't pass anything at all to delete on the top/root level)
-        * missing_ok (`bool`): Do not raise an exception if the key is missing. Defaults to `False`
-        * config_file (`str | Path`, *optional*): Path-like object or path as a string of a location of the config file. Defaults to `"config.json"`
+    Args:
+        key (str): Key to delete.
+        *path (str): Path to the key of the target (pass *[] or don't pass anything at all to delete on the top/root level)
+        missing_ok (bool): Do not raise an exception if the key is missing. Defaults to False.
+        config_file (str | Path, optional): Path-like object or path as a string of a location of the config file. Defaults to "config.json".
 
-    ### Raises:
-        * `KeyError`: Key is not found under path provided and `missing_ok` is `False`
+    Raises:
+        KeyError: Key is not found under path provided and `missing_ok` is False.
     """
     config_data: Dict[str, Any] = json_read(config_file)
 
@@ -161,16 +141,16 @@ async def config_delete(
     missing_ok: bool = False,
     config_file: str | Path = DEFAULT_CONFIG_LOCATION,
 ) -> None:
-    """Set config's key by its path
+    """Delete config's key by its path.
 
-    ### Args:
-        * key (`str`): Key to delete
-        * *path (`str`): Path to the key of the target (pass *[] or don't pass anything at all to delete on the top/root level)
-        * missing_ok (`bool`): Do not raise an exception if the key is missing. Defaults to `False`
-        * config_file (`str | Path`, *optional*): Path-like object or path as a string of a location of the config file. Defaults to `"config.json"`
+    Args:
+        key (str): Key to delete.
+        *path (str): Path to the key of the target (pass *[] or don't pass anything at all to delete on the top/root level)
+        missing_ok (bool): Do not raise an exception if the key is missing. Defaults to False.
+        config_file (str | Path, optional): Path-like object or path as a string of a location of the config file. Defaults to "config.json".
 
-    ### Raises:
-        * `KeyError`: Key is not found under path provided and `missing_ok` is `False`
+    Raises:
+        KeyError: Key is not found under path provided and `missing_ok` is False.
     """
     config_data: Dict[str, Any] = await json_read(config_file)