style: use google docstrings (#16)

docs_gen_files.py

@@ -6,12 +6,9 @@
 def copy_file(source: Path, out: Path):
     """Copy a file into the mkdoc build.
 
-    Parameters
-    ----------
-    source : Path
-        source file
-    out : Path
-        output file (relative to the mkdocs docs/ folder)
+    Args:
+        source (Path): source file
+        out (Path): output file (relative to the mkdocs docs/ folder)
     """
     with open(source, "rb") as f_source:
         with mkdocs_gen_files.open(out, "wb") as f_out:

duties.py

@@ -16,10 +16,8 @@
 def _changelog() -> Tuple[Changelog, str]:
     """Update changelog in-place.
 
-    Returns
-    -------
-    tuple[Changelog, str]
-        changelog object and contents
+    Returns:
+        Tuple[Changelog, str]: changelog object and contents
     """
     return build_and_render(
         repository=".",
@@ -37,10 +35,8 @@ def _changelog() -> Tuple[Changelog, str]:
 def fmt(ctx: Context):
     """Format source code.
 
-    Parameters
-    ----------
-    ctx: Context
-        The context instance (passed automatically).
+    Args:
+        ctx (Context): the context instance (passed automatically).
     """
     ctx.run("isort .", title="Sorting imports")
     ctx.run("black .", title="Code formatting")
@@ -50,10 +46,8 @@ def fmt(ctx: Context):
 def check_dependencies(ctx: Context):
     """Check for vulnerabilities in dependencies.
 
-    Parameters
-    ----------
-    ctx: Context
-        The context instance (passed automatically).
+    Args:
+        ctx (Context): the context instance (passed automatically).
     """
     ctx.run(
         "poetry export --only main | safety check --stdin", title="Dependency checking"
@@ -64,10 +58,8 @@ def check_dependencies(ctx: Context):
 def check_types(ctx: Context):
     """Check that the code is correctly typed.
 
-    Parameters
-    ----------
-    ctx: Context
-        The context instance (passed automatically).
+    Args:
+        ctx (Context): the context instance (passed automatically).
     """
     ctx.run(mypy.run("typer_config"), title="Type checking", pty=PTY)
 
@@ -76,10 +68,8 @@ def check_types(ctx: Context):
 def check_quality(ctx: Context):
     """Check the code quality.
 
-    Parameters
-    ----------
-    ctx: Context
-        The context instance (passed automatically).
+    Args:
+        ctx (Context): the context instance (passed automatically).
     """
     ctx.run("pylint typer_config", title="Linting")
 
@@ -88,10 +78,8 @@ def check_quality(ctx: Context):
 def check_api(ctx: Context) -> None:
     """Check for API breaking changes.
 
-    Parameters
-    ----------
-    ctx: Context
-        The context instance (passed automatically).
+    Args:
+        ctx (Context): the context instance (passed automatically).
     """
     from griffe.cli import check as g_check
 
@@ -106,21 +94,17 @@ def check_api(ctx: Context) -> None:
 def check(ctx: Context):
     """Check it all!
 
-    Parameters
-    ----------
-    ctx: Context
-        The context instance (passed automatically).
+    Args:
+        ctx (Context): the context instance (passed automatically).
     """
 
 
 @duty
 def test(ctx: Context):
     """Run the test suite.
 
-    Parameters
-    ----------
-    ctx: Context
-        The context instance (passed automatically).
+    Args:
+        ctx (Context): the context instance (passed automatically).
     """
     ctx.run("pytest --cov --cov-report=xml", title="Testing")
 
@@ -129,14 +113,10 @@ def test(ctx: Context):
 def docs(ctx: Context, host: str = "127.0.0.1", port: int = 8000) -> None:
     """Serve the documentation (localhost:8000).
 
-    Parameters
-    ----------
-    ctx: Context
-        The context instance (passed automatically).
-    host: str
-        The host to serve the docs from.
-    port: int
-        The port to serve the docs on.
+    Args:
+        ctx (Context): The context instance (passed automatically).
+        host (str, optional): The host to serve the docs from. Defaults to "127.0.0.1".
+        port (int, optional): The port to serve the docs on. Defaults to 8000.
     """
     ctx.run(
         mkdocs.serve(
@@ -152,10 +132,8 @@ def docs(ctx: Context, host: str = "127.0.0.1", port: int = 8000) -> None:
 def changelog(ctx: Context):
     """Update the changelog in-place with latest commits.
 
-    Parameters
-    ----------
-    ctx: Context
-        The context instance (passed automatically).
+    Args:
+        ctx (Context): the context instance (passed automatically).
     """
     ctx.run(_changelog, title="Generating changelog")
 
@@ -164,12 +142,10 @@ def changelog(ctx: Context):
 def release(ctx: Context, version: str = None):
     """Release a new Python package.
 
-    Parameters
-    ----------
-    ctx: Context
-        The context instance (passed automatically).
-    version: str
-        The new version number to use.
+
+    Args:
+        ctx (Context): The context instance (passed automatically).
+        version (str, optional): The new version number to use. Defaults to None.
     """
     if version is None:
         res: Tuple[Changelog, str] = _changelog()

mkdocs.yml

@@ -47,7 +47,7 @@ plugins:
           import:
             - https://docs.python.org/3/objects.inv
           options:
-            docstring_style: numpy
+            docstring_style: google
             show_submodules: true
             enable_inventory: true
             separate_signature: true

typer_config/__init__.py

@@ -11,41 +11,31 @@
 def conf_callback_factory(loader: ConfigLoader) -> ConfigParameterCallback:
     """Typer configuration callback factory.
 
-    Parameters
-    ----------
-    loader : ConfigLoader
-        Config loader function that takes the value passed to the typer CLI and
-        returns a dictionary that is applied to the click context's default map.
-
-    Returns
-    -------
-    ConfigParameterCallback
-        Configuration parameter callback function.
+    Args:
+        loader (ConfigLoader): Config loader function that takes the value
+            passed to the typer CLI and returns a dictionary that is
+            applied to the click context's default map.
+
+    Returns:
+        ConfigParameterCallback: Configuration parameter callback function.
     """
 
     def _callback(
         ctx: Context, param: CallbackParam, param_value: TyperParameterValue
     ) -> TyperParameterValue:
         """Generated typer config parameter callback.
 
-        Parameters
-        ----------
-        ctx : typer.Context
-            typer context (automatically passed)
-        param : typer.CallbackParam
-            typer callback parameter (automatically passed)
-        param_value : TyperParameterValue
-            parameter value passed to typer (automatically passed)
-
-        Returns
-        -------
-        TyperParameterValue
-            must return back the given parameter
-
-        Raises
-        ------
-        typer.BadParameter
-            bad parameter value
+        Args:
+            ctx (typer.Context): typer context (automatically passed)
+            param (typer.CallbackParam): typer callback parameter (automatically passed)
+            param_value (TyperParameterValue): parameter value passed to typer
+                (automatically passed)
+
+        Raises:
+            BadParameter: bad parameter value
+
+        Returns:
+            TyperParameterValue: must return back the given parameter
         """
         try:
             conf = loader(param_value)  # Load config file
@@ -59,94 +49,66 @@ def _callback(
 
 
 yaml_conf_callback: ConfigParameterCallback = conf_callback_factory(yaml_loader)
-"""YAML configuration callback for a typer parameter.
-
-Parameters
-----------
-ctx : typer.Context
-    typer context (automatically passed)
-param : typer.CallbackParam
-    typer callback parameter (automatically passed)
-param_value : TyperParameterValue
-    parameter value passed to typer (automatically passed)
-
-Returns
--------
-TyperParameterValue
-    must return back the given parameter
-
-Raises
-------
-typer.BadParameter
-    bad parameter value
+"""YAML typer config parameter callback.
+
+Args:
+    ctx (typer.Context): typer context (automatically passed)
+    param (typer.CallbackParam): typer callback parameter (automatically passed)
+    param_value (TyperParameterValue): parameter value passed to typer (automatically
+        passed)
+
+Raises:
+    BadParameter: bad parameter value
+
+Returns:
+    TyperParameterValue: must return back the given parameter
 """
 
 json_conf_callback: ConfigParameterCallback = conf_callback_factory(json_loader)
-"""JSON configuration callback for a typer parameter.
-
-Parameters
-----------
-ctx : typer.Context
-    typer context (automatically passed)
-param : typer.CallbackParam
-    typer callback parameter (automatically passed)
-param_value : TyperParameterValue
-    parameter value passed to typer (automatically passed)
-
-Returns
--------
-TyperParameterValue
-    must return back the given parameter
-
-Raises
-------
-typer.BadParameter
-    bad parameter value
+"""JSON typer config parameter callback.
+
+Args:
+    ctx (typer.Context): typer context (automatically passed)
+    param (typer.CallbackParam): typer callback parameter (automatically passed)
+    param_value (TyperParameterValue): parameter value passed to typer (automatically
+        passed)
+
+Raises:
+    BadParameter: bad parameter value
+
+Returns:
+    TyperParameterValue: must return back the given parameter
 """
 
 
 toml_conf_callback: ConfigParameterCallback = conf_callback_factory(toml_loader)
-"""TOML configuration callback for a typer parameter.
-
-Parameters
-----------
-ctx : typer.Context
-    typer context (automatically passed)
-param : typer.CallbackParam
-    typer callback parameter (automatically passed)
-param_value : TyperParameterValue
-    parameter value passed to typer (automatically passed)
-
-Returns
--------
-TyperParameterValue
-    must return back the given parameter
-
-Raises
-------
-typer.BadParameter
-    bad parameter value
+"""TOML typer config parameter callback.
+
+Args:
+    ctx (typer.Context): typer context (automatically passed)
+    param (typer.CallbackParam): typer callback parameter (automatically passed)
+    param_value (TyperParameterValue): parameter value passed to typer (automatically
+        passed)
+
+Raises:
+    BadParameter: bad parameter value
+
+Returns:
+    TyperParameterValue: must return back the given parameter
 """
 
 dotenv_conf_callback: ConfigParameterCallback = conf_callback_factory(dotenv_loader)
-"""Dotenv configuration callback for a typer parameter.
-
-Parameters
-----------
-ctx : typer.Context
-    typer context (automatically passed)
-param : typer.CallbackParam
-    typer callback parameter (automatically passed)
-param_value : TyperParameterValue
-    parameter value passed to typer (automatically passed)
-
-Returns
--------
-TyperParameterValue
-    must return back the given parameter
-
-Raises
-------
-typer.BadParameter
-    bad parameter value
+"""Dotenv typer config parameter callback.
+
+Args:
+    ctx (typer.Context): typer context (automatically passed)
+    param (typer.CallbackParam): typer callback parameter (automatically passed)
+    param_value (TyperParameterValue): parameter value passed to typer (automatically
+        passed)
+
+Raises:
+    BadParameter: bad parameter value
+
+Returns:
+    TyperParameterValue: must return back the given parameter
 """