Merge pull request #27 from Corvan/docs

Add developer documentation

Author: Corvan

.github/workflows/github_pages_static.yml

@@ -3,7 +3,7 @@ name: Deploy static content to Pages
 
 on:
   release:
-    types: [published]
+    types: [released]
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:

docs/development.rst

@@ -1,17 +1,148 @@
 ===========
 Development
 ===========
+If you want to hack on this little library clone it via git
+
+.. code-block:: bash
+
+    git clone https://github.com/Corvan/mailpit-api-client.git
+
+or
+
+.. code-block:: bash
+
+    git clone git@github.com:Corvan/mailpit-api-client.git
+
+Of course you can fork it first on GitHub.
+Then you are easily able to open PRs, which is the preferred way of contributing code.
 
 --------------------
 Install dependencies
 --------------------
+It is recommended to use a virtual environment, in order to separate the dependencies
+for this project from dependencies of other projects.
+There are several tools out there to manage virtual environments, so please consult the
+respective documentantion if you're not using ``venv`` or ``poetry``
+
+If you want to run the tests :ref:`for all possible versions of Python <invoke-tasks>`
+you have to install `Docker Engine <https://docs.docker.com/engine/install/>`_, and the
+`Docker Compose plugin <https://docs.docker.com/compose/install/linux/>`_ on Linux.
+Or you install `Docker Desktop <https://docs.docker.com/get-docker/>`_ on other
+operating system and on Linux.
+
+___
+pip
+___
+
+in order to install the Python dependencies enter the directory of your just cloned
+git repository, activate your virtual environment and type:
 
 .. code-block:: python
 
     pip install -e ".[docs,test,pytest,build]"
 
+
+Now you can start hacking.
+
+______
+poetry
+______
+If you want to use poetry as the manager for your virtual environment, install it if
+necessary and run
+
+.. code-block:: bash
+
+    poetry update
+
+inside the project's directory.
+
+In order to run the :ref:`invoke-tasks` you have to prefix all commands given there with
+
+.. code-block:: bash
+
+    poetry run
+
+so running the Invoke task of unittests you have to type
+
+.. code-block:: bash
+
+    poetry run invoke tests.unit
+
+-----------------
+Running the tests
+-----------------
+This project uses `pytest <https://pytest.org>`_ as testing framework.
+Even the `unittest <https://docs.python.org/3/library/unittest.html>`_ parts are tested
+themselves with ``pytest``.
+
+There are two kinds of tests in this project:
+
+================== =================================================================================================
+test type          description
+================== =================================================================================================
+unit tests         unit tests are tests that check if a functionality works isolated from everything else
+integration tests  integration tests are tests that include dependencies, and check if functionalities work together
+================== =================================================================================================
+
+You can run the tests locally, but then you have to provide a `running Mailpit by
+yourself <https://github.com/axllent/mailpit/blob/develop/README.md>`_ for running the
+integration tests.
+
+.. _invoke-tasks:
+
+____________
+Invoke tasks
+____________
+
+In order to run the tests inside Docker containers, there are
+`Invoke <https://www.pyinvoke.org>`_ tasks that use Docker Compose to set-up all the
+necessary containers and run the checks and tests in them afterwards.
+At the end things are cleaned up again.
+
+.. code-block:: bash
+
+    $ invoke -l
+
+    Available tasks:
+
+    tests.checks
+    tests.integration
+    tests.unit
+
+There are some more tasks, but you can concentrate on those three.
+
+================= ===============================================================================================
+task              description
+================= ===============================================================================================
+tests.checks      runs code checks, like black (code formatting), ruff (linting), and mypy (static code analysis)
+tests.integration runs the integration tests
+tests.unit        runs the unit tests
+================= ===============================================================================================
+
+To run a task, simply type
+
+.. code-block:: bash
+
+    invoke <task>
+
+It is also possible to run multiple tasks at once
+
+.. code-block:: bash
+
+    invoke tests.checks tests.unit tests.integration
+
+For running the tests all the logging outputs are set to debug.
+So running them will produce *a lot* of output, but you will want to know why things
+go wrong.
+If you want to reduce the amount, have a look at :file:`pyproject.toml`
+
+-----------------------
+Build the documentation
+-----------------------
+
 .. code-block:: bash
 
+cd docs
     make clean
     sphinx-apidoc -d 4 -eM -f -o generated ../mailpit
     make html

mailpit/client/api.py

@@ -11,7 +11,7 @@
 
 class API:
     """
-    class representing the message-endpoint of the API
+    class representing the different endpoints of the API
     """
 
     # pylint: disable=too-few-public-methods
@@ -80,9 +80,9 @@ def put_messages(self, ids: List[str], key: str, value: Any):
 
     def get_message(self, message_id: str) -> _models.Message:
         """
+        Send a GET request to get a certain Message by its Message-ID
 
-
-        :param message_id:
+        :param message_id: The Message-ID to get the message by
         """
 
         # pylint: disable = no-member
@@ -97,12 +97,14 @@ def get_message(self, message_id: str) -> _models.Message:
         message = _models.Message.from_json(response.text)
         return message
 
-    def get_message_attachment(self, message_id: str, part_id: str):
+    def get_message_attachment(self, message_id: str, part_id: str) -> str:
         """
+        Send a GET request to the message endpoint with querying for the part_id
+        of an attachment
 
-
-        :param message_id:
-        :param part_id:
+        :param message_id: the Message-ID the attachment belongs to
+        :param part_id: the Part-ID of the attachment to receive
+        :return the attachment's data
         """
         response = _httpx.get(
             f"{self.mailpit_url}/{API.MESSAGE_ENDPOINT}/{message_id}/part/{part_id}",
@@ -112,11 +114,11 @@ def get_message_attachment(self, message_id: str, part_id: str):
         response.raise_for_status()
         return response.text
 
-    def get_message_headers(self, message_id: str):
+    def get_message_headers(self, message_id: str) -> _models.Headers:
         """
+        Send a GET request to get a message's Headers
 
-
-        :param message_id:
+        :param message_id: The Message-ID to get the headers for
         """
         response = _httpx.get(
             f"{self.mailpit_url}/{API.MESSAGE_ENDPOINT}/{message_id}/headers",

pyproject.toml

@@ -39,9 +39,9 @@ test = [
     "mypy>=1.1.1",
     "pylint",
     "respx",
-    "pytest>=7",
 ]
 pytest = [
+    "mailpit-api-client[test]",
     "pytest>=7",
 ]
 build = [
@@ -50,7 +50,7 @@ build = [
 ]
 
 [project.urls]
-repository = "https://github.com/Corvan/mailpit-api-client"
+Repository = "https://github.com/Corvan/mailpit-api-client"
 Documentation = "https://corvan.github.io/mailpit-api-client/"
 
 [tool.poetry]
@@ -77,9 +77,12 @@ black = "*"
 mypy = "^1.4.1"
 pylint = "*"
 respx = "*"
-pytest = "^7"
 
 [tool.poetry.group.pytest.dependencies]
+black = "*"
+mypy = "^1.4.1"
+pylint = "*"
+respx = "*"
 pytest = "^7"
 
 [tool.poetry.group.build.dependencies]