Added sphinx documentation

Author: TCA166

doc/Makefile

@@ -0,0 +1,23 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+doc:
+	sphinx-apidoc -f -o source/ ../gitWebhook/
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

doc/source/conf.py

@@ -0,0 +1,32 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'gitWebhook'
+copyright = '2024, TCA'
+author = 'TCA'
+release = '0.2'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.napoleon",
+]
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']

doc/source/gitWebhook.rst

@@ -0,0 +1,7 @@
+gitWebhook Module
+==================
+
+.. automodule:: gitWebhook
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/source/index.rst

@@ -0,0 +1,26 @@
+.. gitWebhook documentation master file, created by
+   sphinx-quickstart on Thu Apr 18 14:07:22 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to gitWebhook's documentation!
+======================================
+
+gitWebhook is a Python package that provides Flask blueprints for creating webhooks for various git services.
+As of right now GitHub, GitLab and Gitea webhooks are supported.
+The package provides these blueprints as subclasses of Flask's Blueprint class, so they can be easily integrated into existing Flask applications, and expanded with custom behavior.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   modules
+
+   tutorials
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

doc/source/modules.rst

@@ -0,0 +1,36 @@
+gitWebhook
+==========
+
+.. toctree::
+   :maxdepth: 4
+
+   gitWebhook
+
+Webhook Configuration Options
+-----------------------------
+
+The classes contained in this module share some common configuration options that allow you to customize the behavior of the webhook.
+This occurs via arguments passed to the classes during instantiation.
+Since all webhook blueprint classes inherit from :class:`webhookBlueprint`, the configuration options are shared among all classes.
+
+The following configuration options are available:
+
+- **webhookToken** (*str*) - The secret key that the webhook will use to verify the authenticity of incoming requests.
+- **log** (*logging.Logger*) - The logger that the webhook will use to log messages.
+- **name** (*str*) - The name of the webhook blueprint.
+- **github** (*bool*) - Whether the webhook should support GitHub webhooks.
+- **gitlab** (*bool*) - Whether the webhook should support GitLab webhooks.
+- **gitea** (*bool*) - Whether the webhook should support Gitea webhooks.
+- **ipWhitelist** (*List[str]*) - A list of IP addresses that are allowed to send requests to the webhook.
+
+None of these options are mandatory, but you should at least provide a `webhookToken` to ensure that the webhook is secure.
+
+Logging
+-------
+
+All of the blueprints in this module will log events to the provided logger if one is provided.
+All internal errors are logged at the `ERROR` level.
+Arrival of a request is logged at the `INFO` level.
+While all failed requests are logged at the `WARNING` level.
+Use this information to filter what sort of events you want to receive.
+

doc/source/tutorials.rst

@@ -0,0 +1,94 @@
+Tutorials
+==========
+
+Here are some tutorials on how to use gitWebhook.
+All tutorials assume you have git installed on your system, and initialized in the directory you are working in.
+This repository must be configured to connect via SSH to the remote repository using pre-configured SSH keys so that the webhook can just call::
+    
+    git pull    
+
+with no issues.
+
+Automatic deployment with GitHub using Webhooks
+------------------------------------------------
+
+In this tutorial, we will setup a simple automatic deployment system using GitHub Webhooks.
+This will allow you to automatically deploy your code to your server whenever you push to your GitHub repository.
+
+First we are going to set up the backend server that will receive the webhook requests from GitHub.
+We need to have gitWebhook installed on the server, so run::
+
+    pip install gitAppWebhook
+
+to make sure you have both Flask and gitWebhook installed.
+Then create a new file called `webhook.py` and add the following code::
+
+    from gitWebhook import pullerWebhookBlueprint
+    from flask import Flask
+
+    TOKEN = ""
+
+    app = Flask(__name__)
+    wb = pullerWebhookBlueprint(token, url_prefix="/")
+    app.register_blueprint(wb)
+
+    if __name__ == "__main__":
+        app.run()
+
+This code once run will start a Flask server that listens for POST requests on the root URL from either GitHub, GitLab or Gitea using :class:`pullerWebhookBlueprint`.
+The `TOKEN` variable is the secret token that you will use to authenticate the requests from GitHub.
+You can set this to any string you want, but make sure it is a strong secret.
+You can also set the `url_prefix` to any URL you want, but for this tutorial we will use the root URL.
+
+You can now run the server by running the following command::
+
+    python webhook.py
+
+This will start the server on the default Flask url and port.
+Naturally if you are running this on a production server, you will want to use a proper WSGI server like Gunicorn or uWSGI.
+Flask production deployment is outside the scope of this tutorial, but you can find more information in the `Flask documentation <https://flask.palletsprojects.com/en/1.1.x/deploying/>`_.
+
+After the server is running all that is left is to create a webhook on GitHub.
+Go to your repository on GitHub and click on the `Settings` tab.
+Then click on the `Webhooks` tab on the left side of the page.
+Click on the `Add webhook` button and you will be presented with a form to fill in the details of the webhook.
+Don't forget to set the `Content type` to `application/json` and the `Secret` to the same value as the `TOKEN` variable in the `webhook.py` file.
+
+GitHub has a fairly well documented and easy to use webhook interface, so you can find more information on how to set up a webhook on GitHub in the `GitHub documentation <https://developer.github.com/webhooks/creating/>`_.
+If you have configured everything correctly you should now be able to push to your repository and see the changes automatically deployed to your server.
+
+How to setup automatic testing with gitWebhook
+----------------------------------------------
+
+This example is very similar to the previous one, but alongside deploying the code we will also run tests on the code.
+Like previously we will start by setting up the backend server that will receive the webhook requests from GitHub.
+We need to have gitWebhook installed on the server, so run::
+
+    pip install gitAppWebhook
+
+and then create a new file called `webhook.py` and add the following code::
+
+    from gitWebhook import pullerWebhookBlueprint
+    from flask import Flask
+    from tests import yourTestSuite
+
+    TOKEN = ""
+
+    app = Flask(__name__)
+    wb = pullerWebhookBlueprint(token, url_prefix="/", tests=yourTestSuite)
+
+    if __name__ == "__main__":
+        app.run()
+
+After that you need to create a new file called `tests.py` and add the following code::
+
+    import unittest
+
+    class YourTestSuite(unittest.TestCase):
+        def test_something(self):
+            self.assertTrue(True)
+
+    yourTestSuite = unittest.TestLoader().loadTestsFromTestCase(YourTestSuite)
+
+This code will start a Flask server that listens for POST requests on the root URL from either GitHub, GitLab or Gitea using :class:`pullerWebhookBlueprint`.
+Upon receiving a request, the server will pull the changes from git, run the tests in the `tests.py` file, return the result to GitHub and if the tests failed return the repository to the pre merge state.

gitWebhook/__init__.py

@@ -1,8 +1,13 @@
-"""Python module providing Flask blueprints for handling GitHub and GitLab webhooks."""
+"""Python module providing Flask blueprints for handling various git app wehbooks."""
 
 from .webhook import webhookBlueprint
 from .abstractWebhook import gitWebhookBlueprintABC
 from .pullerWebhook import pullerWebhookBlueprint
 from .functionWebhook import functionWebhookBlueprint
 
+__exports__ = [webhookBlueprint, gitWebhookBlueprintABC, pullerWebhookBlueprint, functionWebhookBlueprint]
+
+for e in __exports__:
+    e.__module__ = __name__
+
 __all__ = ["webhookBlueprint", "gitWebhookBlueprintABC", "pullerWebhookBlueprint", "functionWebhookBlueprint"]

gitWebhook/abstractWebhook.py

@@ -7,12 +7,33 @@ class gitWebhookBlueprintABC(ABC):
 
     @abstractmethod
     def __init__(self, webhookToken:str | None, name:str="webhook", *args, **kwargs):
+        """Initialize the webhook blueprint, register the recieveWebhook method as a POST endpoint.
+
+        Args:
+            webhookToken (str | None): The token used to verify the webhook. If None, no verification is done.
+            name (str, optional): Unique blueprint name. Defaults to "webhook".
+            args: Additional arguments to pass to the Blueprint constructor.
+            kwargs: Additional keyword arguments to pass to the Blueprint constructor.
+        """
         ...
 
     @abstractmethod
     def receiveWebhook(self) -> Response:
+        """Method that acts as a POST endpoint for the webhook blueprint.
+
+        Returns:
+            Response: The response to the webhook request.
+        """
         ...
 
     @abstractmethod
     def processWebhook(self, data: dict[str, Any]) -> tuple[int, str]:
+        """Process the webhook data and return a status code and message.
+
+        Args:
+            data (dict[str, Any]): The webhook data.
+
+        Returns:
+            tuple[int, str]: The status code and message.
+        """
         ...

gitWebhook/functionWebhook.py

@@ -1,14 +1,41 @@
 from .webhook import webhookBlueprint
 from typing import Callable, Any
+from logging import Logger
 
 class functionWebhookBlueprint(webhookBlueprint):
     """A subclass of webhookBlueprint that processes the webhook data using a list of functions. The functions should return True if the webhook data is valid, and False otherwise. If the function returns a string, it will be included in the output."""
 
-    def __init__(self, webhookToken: str | None, functions: list[Callable[[dict[str, Any]], bool | str]], *args, **kwargs):
-        super().__init__(webhookToken, *args, **kwargs)
+    def __init__(self, webhookToken: str | None, functions: list[Callable[[dict[str, Any]], bool | str]], log:Logger | None = None, name:str="webhook", github:bool=True, gitlab:bool=True, gitea:bool=True, ipWhitelist:list[str] | None = None, *args, **kwargs):
+        """Initialize the webhook blueprint with a list of functions to process the webhook data.
+
+        Args:
+            webhookToken (str | None): The token used to verify the webhook. If None, no verification is done.
+            functions (list[Callable[[dict[str, Any]], bool  |  str]]): List of functions that will process the webhook data.
+            log (Logger | None, optional): Optional logger that will be used by this blueprint. Defaults to None.
+            name (str, optional): Flask blueprint name. Must be unique. Defaults to "webhook".
+            github (bool, optional): Whether the blueprint should process webhook requests from GitHub. Defaults to True.
+            gitlab (bool, optional): Whether the blueprint should process webhook requests from GitLab. Defaults to True.
+            gitea (bool, optional): Whether the blueprint should process webhook requests from Gitea or other requests using basic auth. Defaults to True.
+            ipWhitelist (list[str] | None, optional): Optional whitelist that all incoming requests will be checked against. Defaults to None.
+            args: Additional arguments to pass to the Blueprint constructor.
+            kwargs: Additional keyword arguments to pass to the Blueprint constructor.
+        """
+        super().__init__(webhookToken, log, name, github, gitlab, gitea, ipWhitelist, *args, **kwargs)
         self.functions = functions
 
     def processWebhook(self, data: dict[str, Any]) -> tuple[int, str]:
+        """Process the webhook data using the list of functions.
+        If any function returns False, the process will return a 400 status code.
+        If any function returns an invalid type, the process will return a 500 status code.
+        Otherwise, the process will return a 200 status code.
+        All function outputs are returned to git as a string.
+
+        Args:
+            data (dict[str, Any]): The webhook data.
+
+        Returns:
+            tuple[int, str]: The status code and message.
+        """
         if self.log is not None:
             self.log.debug(f"Processing webhook: {data}")
         output = []

gitWebhook/pullerWebhook.py

@@ -8,15 +8,39 @@
 class pullerWebhookBlueprint(webhookBlueprint):
     """A subclass of webhookBlueprint that processes the webhook data by pulling from a git repository and running tests."""
 
-    def __init__(self, webhookToken: str | None, tests: TestSuite | None = None, log: Logger | None = None, name: str = "webhook", gitCommand: str = "/usr/bin/git", commandEnv: dict[str, str] | None = None, *args, **kwargs):
-        super().__init__(webhookToken, log, name, *args, **kwargs)
+    def __init__(self, webhookToken: str | None, tests: TestSuite | None = None, log:Logger | None = None, name:str="webhook", github:bool=True, gitlab:bool=True, gitea:bool=True, ipWhitelist:list[str] | None = None, gitCommand: str = "/usr/bin/git", commandEnv: dict[str, str] | None = None, *args, **kwargs):
+        """Initialize the webhook blueprint for pulling from a git repository and running tests.
+
+        Args:
+            webhookToken (str | None): The token used to verify the webhook. If None, no verification is done.
+            tests (TestSuite | None, optional): An optional unittest.TestSuite that will be ran after pulling from git. Defaults to None.
+            log (Logger | None, optional): Optional logger that will be used by this blueprint. Defaults to None.
+            name (str, optional): Flask blueprint name. Must be unique. Defaults to "webhook".
+            github (bool, optional): Whether the blueprint should process webhook requests from GitHub. Defaults to True.
+            gitlab (bool, optional): Whether the blueprint should process webhook requests from GitLab. Defaults to True.
+            gitea (bool, optional): Whether the blueprint should process webhook requests from Gitea or other requests using basic auth. Defaults to True.
+            ipWhitelist (list[str] | None, optional): Optional whitelist that all incoming requests will be checked against. Defaults to None.
+            gitCommand (str, optional): Path to the git executable. Defaults to "/usr/bin/git".
+            commandEnv (dict[str, str] | None, optional): Optional environment that will be used by git during pulling. Defaults to None.
+        """
+        super().__init__(webhookToken, log, name, github, gitlab, gitea, ipWhitelist, *args, **kwargs)
         self.tests = tests
         self.gitCommand = gitCommand
         if commandEnv is None:
             commandEnv = dict(GIT_SSH_COMMAND="/usr/bin/ssh")
         self.commandEnv = commandEnv
 
     def processWebhook(self, data: dict[str, Any]) -> tuple[int, str]:
+        """Process the webhook data by pulling from a git repository and running tests.
+        If the tests are not provided, only the pull will be done.
+        Otherwise the tests will be ran and if they fail the merge will be aborted.
+
+        Args: 
+            data (dict[str, Any]): The webhook data.
+
+        Returns:
+            tuple[int, str]: The status code and message.
+        """
         if self.log is not None:
             self.log.debug(f"Processing webhook: {data}")
         process = run([self.gitCommand, "pull"], env=self.commandEnv)