Adding docstrings and introducing sphinx draft (#12)

Author: giograno

.github/workflows/docs.yml

@@ -0,0 +1,42 @@
+name: Build sphinx documentation
+
+on:
+  push:
+    paths:
+      - 'docs/**'
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v3
+
+    - name: Install project
+      run: |
+        make install-dev
+
+    - name: Generate docs
+      run: |
+        source .venv/bin/activate
+        make sphinx-docs
+
+    - name: Upload artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: html-docs
+        path: docs/_build/html/
+
+    - name: Deploy
+      uses: peaceiris/actions-gh-pages@v3
+      if: github.ref == 'refs/heads/main'
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: docs/_build/html

Makefile

@@ -23,6 +23,11 @@ clean-generated:	## Cleanup generated code
 generate:			## Generate the code from the OpenAPI specs
 	./bin/generate.sh
 
+sphinx-docs:				## Generate the documentation; uses the sphinx-generated Makefile in docs to clean and build html
+	($(VENV_RUN); sphinx-apidoc --implicit-namespaces -o docs localstack-sdk-python/localstack)
+	$(MAKE) -C docs clean
+	$(MAKE) -C docs html
+
 format:
 	($(VENV_RUN); python -m ruff format --exclude packages .; python -m ruff check --output-format=full --exclude packages --fix .)
 

docs/Makefile

@@ -0,0 +1,21 @@
+# Minimal makefile for Sphinx documentation
+# Mostly use by the project Makefile to access the clean and html targets
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+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
+
+# 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)

docs/_static/localstack-horizontal.png

@@ -0,0 +1,59 @@
+# 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
+
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath("../localstack-sdk-python/localstack"))
+
+
+def _get_version() -> str:
+    with open(os.path.abspath("../VERSION"), "r") as f:
+        version = f.read()
+        return version
+
+
+project = "LocalStack Python SDK"
+copyright = "2024, LocalStack Team"
+author = "LocalStack Team"
+release = _get_version()
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+# enable auto-doc extension
+extensions = ["sphinx.ext.autodoc"]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "alabaster"
+html_static_path = ["_static"]
+
+html_sidebars = {
+    "**": [
+        "about.html",
+        "searchfield.html",
+        "navigation.html",
+    ]
+}
+
+html_theme_options = {
+    "extra_nav_links": {
+        "Source": "https://github.com/localstack/localstack-sdk-python",
+        "Issues": "https://github.com/localstack/localstack-sdk-python/issues",
+        "PyPI": "https://pypi.org/project/localstack-sdk-python/",
+    },
+    "description": "Python SDK to interact with LocalStack developer endpoints",
+    "github_user": "localstack",
+    "github_repo": "localstack-sdk-python",
+}

docs/conf.py

@@ -0,0 +1,52 @@
+.. image:: _static/localstack-horizontal.png
+    :align: center
+    :target: https://localstack.cloud
+
+This is the documentation for the Python
+`LocalStack's SDK <https://github.com/localstack/localstack-sdk-python>`_.
+
+LocalStack offers a number of developer endpoints to programmatically interact
+with LocalStack's features.
+
+The complete OpenAPI spec can be found in the
+`OpenAPI repository <https://github.com/localstack/openapi>`_.
+
+Installation
+------------
+
+We recommend to user virtual environments to manage the dependencies of your project.
+
+To create and activate a virtual environment inside your project run:
+
+.. code-block:: shell
+
+  python3 -m venv venv
+
+You can activate the correspondent provider with:
+
+.. code-block:: shell
+
+    . venv/bin/activate
+
+With the activated environment, use the following command to install the LocalStack Python SDK.
+
+.. code-block:: shell
+
+  pip install localstack-sdk-python
+
+Getting Started
+---------------
+
+To learn about the basic SDK concepts and see how you can use it, please have a look at our
+official `LocalStack documentation <https://docs.localstack.cloud/user-guide/tools/localstack-sdk/python/>`_.
+
+API Reference
+-------------
+
+If you are looking for information on a specific function, class or
+method, this part of the documentation is for you.
+
+.. toctree::
+   :maxdepth: 1
+
+   modules

docs/index.rst

@@ -0,0 +1,7 @@
+API Reference
+=============
+
+.. toctree::
+   :maxdepth: 4
+
+   localstack.sdk

docs/modules.rst

@@ -1,7 +1,7 @@
 import json
 
-from localstack.clients import BaseClient
 from localstack.sdk.api.aws_api import AwsApi
+from localstack.sdk.clients import BaseClient
 from localstack.sdk.models import (
     Message,
     SesSentEmail,
@@ -36,6 +36,12 @@ def _from_sqs_query_to_json(xml_dict: dict) -> list[Message]:
 
 
 class AWSClient(BaseClient):
+    """
+    The client to interact with all the LocalStack's AWS endpoints.
+    These endpoints offer specific features in addition to the ones offered by the AWS services. For instance,
+    access all the messages withing a SQS without the side effect of deleting them.
+    """
+
     def __init__(self, **kwargs) -> None:
         super().__init__(**kwargs)
         self._client = AwsApi(self._api_client)
@@ -45,12 +51,26 @@ def __init__(self, **kwargs) -> None:
     ########
 
     def list_sqs_messages(self, account_id: str, region: str, queue_name: str) -> list[Message]:
+        """
+        Lists all the SQS messages in a given queue in a specific account id and region, without any side effect.
+
+        :param account_id: the account id of the queue
+        :param region: the region of the queue
+        :param queue_name: the name of the queue
+        :return: the list of messages in the queue
+        """
         response = self._client.list_sqs_messages_with_http_info(
             account_id=account_id, region=region, queue_name=queue_name
         )
         return _from_sqs_query_to_json(json.loads(response.raw_data))
 
-    def list_sqs_messages_from_queue_url(self, queue_url) -> list[Message]:
+    def list_sqs_messages_from_queue_url(self, queue_url: str) -> list[Message]:
+        """
+        Lists all the SQS messages in a given queue, without any side effect.
+
+        :param queue_url: the URL of the queue
+        :return: the list of messages in the queue
+        """
         response = self._client.list_all_sqs_messages_with_http_info(queue_url=queue_url)
         return _from_sqs_query_to_json(json.loads(response.raw_data))
 
@@ -61,10 +81,23 @@ def list_sqs_messages_from_queue_url(self, queue_url) -> list[Message]:
     def get_ses_messages(
         self, id_filter: str | None = None, email_filter: str | None = None
     ) -> list[SesSentEmail]:
+        """
+        Returns all the in-memory saved SES messages. They can be filtered by message ID and/or message source.
+
+        :param id_filter: the message id used as filter for the SES messages
+        :param email_filter: the message source filter
+        :return: a list of email sent with SES
+        """
         response = self._client.get_ses_messages(id=id_filter, email=email_filter)
         return response.messages
 
     def discard_ses_messages(self, id_filter: str | None = None) -> None:
+        """
+        Clears all SES messages. An ID filter can be provided to delete only a specific message.
+
+        :param id_filter: the id filter
+        :return: None
+        """
         return self._client.discard_ses_messages(id=id_filter)
 
     ########
@@ -77,6 +110,15 @@ def get_sns_sms_messages(
         account_id: str = "000000000000",
         region: str = "us-east-1",
     ) -> SNSSMSMessagesResponse:
+        """
+        Returns all SMS messages published to a phone number.
+
+        :param phone_number: the phone number to which the messages have been published. If not specified, all messages
+            are returned.
+        :param account_id: the AWS Account ID from which the messages have been published. '000000000000' by default
+        :param region:  the AWS region from which the messages have been published. us-east-1 by default
+        :return:
+        """
         return self._client.get_sns_sms_messages(
             phone_number=phone_number, account_id=account_id, region=region
         )
@@ -87,6 +129,15 @@ def discard_sns_sms_messages(
         account_id: str = "000000000000",
         region: str = "us-east-1",
     ) -> None:
+        """
+        Discards all SMS messages published to a phone number.
+
+        :param phone_number: the phone number to which the messages have been published. If not specified, all messages
+            are deleted.
+        :param account_id: the AWS Account ID from which the messages have been published. '000000000000' by default
+        :param region:  the AWS region from which the messages have been published. us-east-1 by default
+        :return: None
+        """
         return self._client.discard_sns_sms_messages(
             phone_number=phone_number, account_id=account_id, region=region
         )
@@ -97,6 +148,15 @@ def get_sns_endpoint_messages(
         account_id: str = "000000000000",
         region: str = "us-east-1",
     ) -> SNSPlatformEndpointResponse:
+        """
+        Returns all the messages published to a platform endpoint.
+
+        :param endpoint_arn: the ARN to which the messages have been published. If not specified, will return all the
+            messages.
+        :param account_id: the AWS Account ID from which the messages have been published. 000000000000 if not specified
+        :param region: the AWS region from which the messages have been published. us-east-1 by default
+        :return: a response with the list of messages and the queried region
+        """
         return self._client.get_sns_endpoint_messages(
             endpoint_arn=endpoint_arn, account_id=account_id, region=region
         )
@@ -107,6 +167,15 @@ def discard_sns_endpoint_messages(
         account_id: str = "000000000000",
         region: str = "us-east-1",
     ) -> None:
+        """
+        Discards all the messaged published to a platform endpoint.
+
+        :param endpoint_arn: the ARN to which the messages have been published. If not specified, will discard all the
+            messages.
+        :param account_id: the AWS Account ID from which the messages have been published. 000000000000 if not specified
+        :param region: the AWS region from which the messages have been published. us-east-1 by default
+        :return: None
+        """
         return self._client.discard_sns_endpoint_messages(
             endpoint_arn=endpoint_arn, account_id=account_id, region=region
         )