0.1.4 - Modify firm_info tag and add documentation

docs/django_app/index.rst → docs/firm_info/index.rst

@@ -1,10 +1,14 @@
-.. _intro_django-app:
+.. _intro_firm-info:
 
 ==================
-Django application
+Django firm info
 ==================
 
 .. toctree::
    :maxdepth: 2
 
    models.rst
+
+   serializers.rst
+
+   templatetags.rst

docs/firm_info/models.rst

@@ -0,0 +1,9 @@
+.. _intro_firm-info_models:
+
+======
+Models
+======
+
+.. automodule:: firm_info.models
+    :members: FirmContact, Link, SocialSharing, Tracking, AppsBanner, 
+    :exclude-members: DoesNotExist, MultipleObjectsReturned

docs/firm_info/serializers.rst

@@ -0,0 +1,9 @@
+.. _intro_firm-info_serializers:
+
+===========
+Serializers
+===========
+
+.. automodule:: firm_info.serializers
+    :members: SerializeFirmError, _format_address, serialize_firm_info, serialize_firm_social, serialize_firm_description, serialize_firm_social_sharing, serialize_firm_apps_banner
+    :exclude-members: DoesNotExist, MultipleObjectsReturned

docs/firm_info/templatetags.rst

@@ -0,0 +1,9 @@
+.. _intro_firm-info_templatetags:
+
+============
+Templatetags
+============
+
+.. automodule:: firm_info.templatetags.firm_info
+    :members: firm_contact, firm_social_links, firm_description, firm_logos, firm_social_shares, firm_tag_analytic, app_banner
+    :exclude-members: DoesNotExist, MultipleObjectsReturned

docs/index.rst

@@ -8,7 +8,7 @@ User’s Guide
    :maxdepth: 2
 
    install.rst
-   django_app/index.rst
+   firm_info/index.rst
 
 
 Developer’s Guide

firm_info/models.py

@@ -8,6 +8,26 @@
 
 
 class FirmContact(models.Model):
+    """
+    Represents the contact information for a firm.
+
+    Args:
+        models.Model: The base model class provided by Django.
+
+    Attributes:
+        phone_number (CharField): The phone number of the firm.
+        email (EmailField): The email address of the firm.
+        address (CharField): The address of the firm.
+        postal_code (CharField): The postal code of the firm.
+        city (CharField): The city of the firm.
+        country (CharField): The country of the firm.
+        baseline (CharField): The baseline of the firm.
+        short_description (TextField): The short description of the firm.
+        logo (SmartMediaField): The logo of the firm.
+        logo_invert (SmartMediaField): The inverted logo of the firm.
+        favicon (SmartMediaField): The favicon of the firm.
+        objects (SingletonManager): The manager for the FirmContact model.
+    """
     phone_number = models.CharField(max_length=20, null=False, blank=True, default="")
     email = models.EmailField(null=False, blank=True, default="")
     address = models.CharField(max_length=255, null=False, blank=True, default="")
@@ -61,6 +81,17 @@ def __str__(self):
 
 
 class Link(models.Model):
+    """
+    Represents a social network link.
+
+    Attributes:
+        SOCIAL_NETWORK_NAMES (tuple): Choices for the name field representing
+            various social network names.
+        name (CharField): The name of the social network.
+        url (URLField): The URL of the social network link.
+        client_contact (ForeignKey): The foreign key to the FirmContact model
+            representing the client contact.
+    """
     SOCIAL_NETWORK_NAMES = (
         ("linkedin", "linkedin"),
         ("facebook", "facebook"),
@@ -93,6 +124,15 @@ class Meta:
 
 
 class SocialSharing(models.Model):
+    """
+    Represents social media sharing information.
+
+    Attributes:
+        og_image (SmartMediaField): The OG image for social media sharing.
+        og_description (TextField): The OG description for social media sharing.
+        og_twitter_site (CharField): The OG Twitter site for social media sharing.
+    """
+
     og_image = SmartMediaField(
         _("OG Image"),
         null=True,
@@ -135,6 +175,13 @@ class Meta:
 
 
 class Tracking(models.Model):
+    """
+    Represents tracking information.
+
+    Attributes:
+        tag_analytic (CharField): The tag analytic for tracking.
+    """
+
     tag_analytic = models.CharField(
         max_length=100,
         null=False,
@@ -149,6 +196,21 @@ class Meta:
 
 
 class AppsBanner(models.Model):
+    """
+    Represents an app banner in the Django firm_info models.
+
+    Args:
+        models.Model: The base model class provided by Django.
+
+    Attributes:
+        APPS_CHOICES (list): A list of tuples representing the available choices for
+            the application type.
+        application_type (models.CharField): The type of the application.
+        image (SmartMediaField): The image associated with the app banner.
+        title (models.CharField): The title of the app banner.
+        description (HTMLField): The description of the app banner.
+    """
+
     APPS_CHOICES = [
         ("application_sent", _("Application sent")),
         ("free_apply", _("Free apply")),

firm_info/serializers.py

@@ -1,12 +1,23 @@
 class SerializeFirmError(Exception):
-    """
-    Custom exception to handle errors during Firm informations serialization.
-    """
-
     pass
 
 
 def _format_address(firm_info: dict) -> str:
+    """
+    Formats the address using the firm information.
+
+    Args:
+        firm_info (dict): The firm information with the following keys:
+
+            - "address": The address of the firm.
+            - "postal_code": The postal code of the firm.
+            - "city": The city of the firm.
+            - "country": The country of the firm.
+
+    Returns:
+        str: The formatted address string in the format
+          `"{address}, {postal_code} {city} {country}"`.
+    """
     return "{}, {} {} {}".format(
         firm_info.get("address"),
         firm_info.get("postal_code"),
@@ -17,61 +28,58 @@ def _format_address(firm_info: dict) -> str:
 
 def serialize_firm_info(queryset):
     """
-    Serialize FirmContact unique instance.
-
+    Serializes the firm information from a queryset.
 
     Args:
-        `FirmContact` Queryset
-
-    Raises:
-        SerializeFirmError
+        queryset: The queryset containing the firm information.
 
     Returns:
-        (dict): email phone and address of firm as serialized data
-
-        Sample:
-        ```
-        {
-            "email": "[email protected]",
-            "phone": "003369856321",
-            "address": "1 avenue Charles de Gaulle, 99999 Paris"
-        }
-        ```
+        dict: the serialized firm information with the following keys:
+
+            - "email": The email address of the firm.
+            - "phone": The phone number of the firm.
+            - "full_address": The formatted full address of the firm.
+            - "address": The address of the firm.
+            - "postal_code": The postal code of the firm.
+            - "city": The city of the firm.
+            - "country": The country of the firm.
+
+    Raises:
+        SerializeFirmError: Raised when an error occurs during serialization.
     """
+
     try:
         firm_info = queryset.values(
             "phone_number", "email", "address", "postal_code", "city", "country"
         ).first()
         return {
             "email": firm_info.get("email"),
             "phone": firm_info.get("phone_number"),
-            "address": _format_address(firm_info),
+            "full_address": _format_address(firm_info),
+            "address": firm_info.get("address"),
+            "postal_code": firm_info.get("postal_code"),
+            "city": firm_info.get("city"),
+            "country": firm_info.get("country"),
         }
     except Exception as err:
         raise SerializeFirmError from err
 
 
 def serialize_firm_social(queryset):
     """
-    Serialize Firm social networks urls.
+    Serializes the firm social media information from a queryset.
 
     Args:
-        `Link` Queryset
-
-    Raises:
-        SerializeFirmError
+        queryset: The queryset containing the firm social media information.
 
     Returns:
-        (dict): social network name as dict key, url as dict value.
+        dict: The serialized firm social media information with the social media names
+        as keys and their corresponding URLs as values.
 
-        Sample:
-        ```python
-        {
-            "facebook": "www.site.com",
-            "instagram": "www.site2.com"
-        }
-        ```
+    Raises:
+        SerializeFirmError: Raised when an error occurs during serialization.
     """
+
     try:
         firm_socials = list(
             queryset.values(
@@ -89,25 +97,19 @@ def serialize_firm_social(queryset):
 
 def serialize_firm_description(queryset):
     """
-    Serialize FirmContact unique instance.
-
+    Serializes the firm description from a queryset.
 
     Args:
-        `FirmContact` Queryset
-
-    Raises:
-        SerializeFirmError
+        queryset: The queryset containing the firm description.
 
     Returns:
-        (dict): baseline and short_description of firm as serialized data
+        dict: The serialized firm description with the following keys:
 
-        Sample:
-        ```
-        {
-            "baseline": "Non eram nescius, Brute, cum, quae summis ingeniis",
-            "short_description": "Quamquam, si plane sic verterem Platonem"
-        }
-        ```
+            - "baseline": The baseline of the firm.
+            - "short_description": The short description of the firm.
+
+    Raises:
+        SerializeFirmError: Raised when an error occurs during serialization.
     """
     try:
         firm_info = queryset.values("baseline", "short_description").first()
@@ -121,25 +123,20 @@ def serialize_firm_description(queryset):
 
 def serialize_firm_social_sharing(obj):
     """
-    Serialize Firm social networks sharing urls.
+    Serialize Firm social networks sharing URLs.
 
     Args:
-        `SocialSharing` Queryset
-
-    Raises:
-        SerializeFirmError
+        obj (QuerySet): The `SocialSharing` queryset.
 
     Returns:
-        (dict): og_image, og_description and og_twitter_site as serialized data
-
-        Sample:
-        ```python
-        {
-            "og_image": SmartMediaField(),
-            "og_description": TextField(),
-            "og_twitter_site": CharField(),
-        }
-        ```
+        dict: The serialized data with the following keys:
+
+            - og_image (SmartMediaField): The OG image for social media sharing.
+            - og_description (TextField): The OG description for social media sharing.
+            - og_twitter_site (CharField): The OG Twitter site for social media sharing.
+
+    Raises:
+        SerializeFirmError: Raised when an error occurs during serialization.
     """
 
     try:
@@ -154,6 +151,23 @@ def serialize_firm_social_sharing(obj):
 
 
 def serialize_firm_apps_banner(obj):
+    """
+    Serializes an instance of the AppsBanner model into a dictionary.
+
+    Args:
+        obj: The AppsBanner object to be serialized.
+
+    Returns:
+        dict: The serialized data with the following keys:
+
+            - "title": The title of the `AppsBanner`.
+            - "description": The description of the AppsBanner.
+            - "image": The image associated with the AppsBanner.
+
+    Raises:
+        SerializeFirmError: Raised when an error occurs during serialization.
+"""
+
     try:
         return {
             "title": obj.title,

firm_info/templates/tests/templatetags/firm_info/test_firm_contact.html

@@ -1,3 +1,7 @@
 <p>Email: {{ email }}</p>
 <p>Phone: {{ phone }}</p>
-<p>Address: {{ address }}</p>
+<p>Full address: {{ full_address }}</p>
+<p>Address: {{ address }}</p>
+<p>city: {{ city }}</p>
+<p>postal code: {{ postal_code }}</p>
+<p>country: {{ country }}</p>