Merge pull request #43 from psadi/feature/license_and_docs

licensing and docs

README.md

@@ -1,7 +1,7 @@
 ## Bitbucket CLI (bb)
 Work seamlessly with Bitbucket from the command line
 
-![](https://img.shields.io/badge/license-MIT-green.svg?style=flat)
+[![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
 [![Continuous Integration](https://github.com/psadi/bbcli/actions/workflows/ci.yml/badge.svg)](https://github.com/psadi/bbcli/actions/workflows/ci.yml)
 [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=psadi_bbcli&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=psadi_bbcli)
 <a href="https://www.buymeacoffee.com/addy3494" target="_blank"><img src="https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png" alt="Buy Me A Coffee" style="height: 22px !important;width: 100px !important;" ></a>
@@ -180,4 +180,6 @@ A huge thanks to,
 * [pdm-project/pdm](https://github.com/pdm-project/pdm)
 
 ### LICENSE
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details
+![](https://www.gnu.org/graphics/agplv3-155x51.png)
+
+This project is licensed under the GNU Affero General Public License v3.0 - see the [**LICENSE**](LICENSE) file for details.

bb/__init__.py

@@ -1,4 +1,24 @@
 # -*- coding: utf-8 -*-
+
+############################################################################
+# Bitbucket CLI (bb): Work seamlessly with Bitbucket from the command line
+#
+# Copyright (C) 2022  P S, Adithya (psadi) ([email protected])
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as
+# published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+############################################################################
+
 """
 bb: a cli for bitbucket.
 """
@@ -15,7 +35,13 @@
 
 def version_callback(value: bool) -> None:
     """
-    Prints the version of bb and exits the program.
+    Prints the version of bb and exits the program if the value is True.
+
+    Parameters:
+        value (bool): A boolean value indicating whether to print the version or not.
+
+    Returns:
+        None
     """
     if value:
         console.print(f"bb version: {version}")
@@ -46,7 +72,14 @@ def callback(
     version: bool = typer.Option(None, "--version", callback=version_callback),
 ):
     """
-    Entry point for the bb CLI. Handles global flags like --verbose and --version.
+    This function is a callback function that sets the verbosity level and version information.
+
+    Args:
+        verbose (bool, optional): A boolean indicating whether to enable verbose mode. Defaults to False.
+        version (bool, optional): A boolean indicating whether to display the version information. Defaults to None.
+
+    Returns:
+        None
     """
     if verbose:
         common_vars.state["verbose"] = True

bb/__version__.py

@@ -1,4 +1,24 @@
 # -*- coding: utf-8 -*-
+
+############################################################################
+# Bitbucket CLI (bb): Work seamlessly with Bitbucket from the command line
+#
+# Copyright (C) 2022  P S, Adithya (psadi) ([email protected])
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as
+# published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+############################################################################
+
 """
 bb.__version__
   Sets the packge version, picked dynamically by

bb/auth/__init__.py

@@ -1,7 +1,29 @@
 # -*- coding: utf-8 -*-
 
+############################################################################
+# Bitbucket CLI (bb): Work seamlessly with Bitbucket from the command line
+#
+# Copyright (C) 2022  P S, Adithya (psadi) ([email protected])
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as
+# published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+############################################################################
+
 """
 bb: auth - validates and configures the auth details
+
+Defines commands to configure, test, and view the authentication status for
+a Bitbucket CLI tool.
 """
 
 import typer
@@ -13,9 +35,18 @@
 _auth: typer.Typer = typer.Typer(add_completion=False, no_args_is_help=True)
 
 
-@_auth.command()
+@_auth.command(help="Configure bbcli to work with Bitbucket")
 def setup() -> None:
-    """Configure bbcli to work with bitbucket"""
+    """
+    The `setup` function checks for a configuration file and sets up authentication if not found.
+
+    Args:
+    -   :param: The `setup` function does not take any parameters
+    Raises:
+    -   :raises: This function does not raise any exceptions
+    Returns:
+    -   :rtype: None
+    """
 
     @error_handler
     def _setup() -> None:
@@ -39,9 +70,19 @@ def _setup() -> None:
     _setup()
 
 
-@_auth.command()
+@_auth.command(help="Test configuration & connection")
 def test() -> None:
-    """Test configuration & connection"""
+    """
+    The function `test` contains an inner function `_test` that checks for the presence of configuration
+    and validates it.
+
+    Args:
+    -   :param: The `test` function does not take any parameters
+    Raises:
+    -   :raises: This function does not raise any exceptions
+    Returns:
+    -   :rtype: None
+    """
 
     @error_handler
     def _test() -> None:
@@ -52,9 +93,22 @@ def _test() -> None:
     _test()
 
 
-@_auth.command()
+@_auth.command(help="View authentication config status")
 def status(token: bool = typer.Option(False, help="Display auth token")) -> None:
-    """View authentication config status"""
+    """
+    Displays the status of the authentication token and related configuration
+    information for a Bitbucket connection.
+
+    Args:
+    -   :param token: The `token` parameter in the `status` function is a boolean type with a default value
+        of `False`. It is used to determine whether the authentication token should be displayed or masked
+        when the function is called
+    -   :type token: bool
+    Raises:
+    -   :raises: This function does not raise any exceptions
+    Returns:
+    -   :rtype: None
+    """
 
     @error_handler
     def _status(token: bool) -> None: