added doc comments to all formatters

html_to_django/formatters/__init__.py

@@ -1,3 +1,12 @@
+"""
+formatters
+
+This package contains modules that define various formatters for modifying a BeautifulSoup object in place.
+
+Each formatter module contains a `format` function that performs a specific modification on the BeautifulSoup object.
+
+The `formatters` list in this package contains all the formatter modules for easy access and usage.
+"""
 from . import (for_formatter, if_formatter, var_formatter, block_formatter, static_formatter, attr_formatter,
                for_wrap_formatter, unwrap_formatter, include_formatter, remove_default_formatter, command_formatter,
                style_formatter, style_raw_formatter)

html_to_django/formatters/command_formatter.py

@@ -1,3 +1,16 @@
+"""
+command_formatter.py
+
+This module contains a function `format` that modifies a BeautifulSoup object in place.
+The function searches for all elements with the attribute "dj-command". The value of "dj-command" is expected to be a
+string representing a Django template command. For each found element, it replaces the element's content with the Django
+template command, using the value of "dj-command" as the command. Then it removes the element's original tag, leaving
+only the Django template command.
+
+Example:
+    If an element is <div dj-command="url 'index'"></div>,
+    after processing, it becomes {% url 'index' %}.
+"""
 from bs4 import BeautifulSoup
 
 

html_to_django/formatters/for_formatter.py

@@ -1,3 +1,16 @@
+"""
+for_formatter.py
+
+This module contains a function `format` that modifies a BeautifulSoup object in place.
+The function searches for all elements with the attribute "dj-for". The value of "dj-for" is expected to be a
+string representing a Django template for loop. For each found element, it inserts a Django template for loop
+before the element and an endfor tag after the element, using the value of "dj-for" as the loop. Then it removes
+the element's original tag, leaving only the Django template for loop.
+
+Example:
+    If an element is <div dj-for="item in list"></div>,
+    after processing, it becomes {% for item in list %}{% endfor %}.
+"""
 from bs4 import BeautifulSoup
 
 

html_to_django/formatters/for_wrap_formatter.py

@@ -1,3 +1,16 @@
+"""
+for_wrap_formatter.py
+
+This module contains a function `format` that modifies a BeautifulSoup object in place.
+The function searches for all elements with the attribute "dj-for-wrap". The value of "dj-for-wrap" is expected to be a
+string representing a Django template for loop. For each found element, it inserts a Django template for loop
+before the element and an endfor tag after the element, using the value of "dj-for-wrap" as the loop. Then it removes
+the "dj-for-wrap" attribute from the element, leaving the element wrapped in the Django template for loop.
+
+Example:
+    If an element is <div dj-for-wrap="item in list">Content</div>,
+    after processing, it becomes {% for item in list %}<div>Content</div>{% endfor %}.
+"""
 from bs4 import BeautifulSoup
 
 

html_to_django/formatters/if_formatter.py

@@ -1,3 +1,17 @@
+"""
+if_formatter.py
+
+This module contains a function `format` that modifies a BeautifulSoup object in place.
+The function searches for all elements with the attribute "dj-if". The value of "dj-if" is expected to be a
+string representing a Django template if condition. For each found element, it inserts a Django template if tag
+before the element. If there are subsequent siblings with "dj-elif" or "dj-else" attributes, it also processes them
+appropriately to form a complete Django template if-elif-else structure. Then it removes the original tags, leaving
+only the Django template if-elif-else structure.
+
+Example:
+    If the elements are <div dj-if="condition1">Test</div><div dj-elif="condition2">Test2</div><div dj-else>Test3</div>,
+    after processing, they become {% if condition1 %}Test{% elif condition2 %}Test2{% else %}Test3{% endif %}.
+"""
 from bs4 import BeautifulSoup
 
 

html_to_django/formatters/include_formatter.py

@@ -1,3 +1,16 @@
+"""
+include_formatter.py
+
+This module contains a function `format` that modifies a BeautifulSoup object in place.
+The function searches for all elements with the attribute "dj-include". The value of "dj-include" is expected to be a
+string representing a Django template include command. For each found element, it replaces the element's content with
+the Django template include command, using the value of "dj-include" as the command.
+Then it removes the "dj-include" attribute from the element.
+
+Example:
+    If an element is <div dj-include="template_name.html"></div>,
+    after processing, it becomes {% include "template_name.html" %}.
+"""
 from bs4 import BeautifulSoup
 
 

html_to_django/formatters/remove_default_formatter.py

@@ -1,3 +1,15 @@
+"""
+remove_default_formatter.py
+
+This module contains a function `format` that modifies a BeautifulSoup object in place.
+The function searches for the "html" element with the attribute "dj-remove-default". If such an element is found,
+the function removes the Doctype, "head" element, and "script" element within the "body" element from the BeautifulSoup
+object. It also unwraps the "body" and "html" elements, leaving only the remaining content of the "body" element.
+
+Example:
+    If the html is <!DOCTYPE html><html dj-remove-default><head></head><body><script></script>Content</body></html>,
+    after processing, it becomes Content.
+"""
 from bs4 import BeautifulSoup, Doctype, Tag
 
 

html_to_django/formatters/static_formatter.py

@@ -1,3 +1,16 @@
+"""
+static_formatter.py
+
+This module contains a function `format` that modifies a BeautifulSoup object in place.
+The function searches for all elements with the attribute "dj-static". The value of "dj-static" is expected to be a
+string representing a tag and a static file path separated by a semicolon. For each found element, it replaces the value
+of the specified tag with a Django template static command, using the specified static file path.
+Then it removes the "dj-static" attribute from the element.
+
+Example:
+    If an element is <img dj-static="src;images/pic.jpg">,
+    after processing, it becomes <img src="{% static 'images/pic.jpg' %}">.
+"""
 from bs4 import BeautifulSoup
 
 

html_to_django/formatters/style_formatter.py

@@ -1,7 +1,48 @@
+"""
+style_formatter.py
+
+This module contains a function `format` that modifies a BeautifulSoup object in place. It also contains two helper
+functions, `parse_style` and `style_to_string`.
+
+The `parse_style` function takes a string of CSS styles and parses it into a dictionary where keys are
+CSS property names and values are the corresponding CSS values.
+
+The `style_to_string` function takes a dictionary of CSS styles and converts it into a string representation.
+
+The `format` function searches for all elements with the attribute "dj-style". For each found element, it parses the
+existing style attributes (if any), merges them with the styles specified in "dj-style", and replaces the
+style attribute with the merged styles. The values of the "dj-style" attribute are expected to be strings with pairs of
+CSS properties, values, and value types separated by semicolons (;), and each triplet separated by tildes (~).
+The value is inserted into the style attribute in Django template variable format (i.e., "{{ value }}").
+If a value type is specified, it is appended to the value in the style attribute.
+The value type can be omitted if not needed. In that case make sure to keep the semicolon at the end of the value.
+Then it removes the "dj-style" attribute from the element.
+
+Example:
+    If an element is <div style="color:red" dj-style="background-color;color;px">,
+    after processing, it becomes <div style="color:red;background-color:{{ color }}px">.
+"""
 from bs4 import BeautifulSoup
 
 
 def parse_style(style: str) -> dict[str, str]:
+    """
+    Parses a string of CSS styles into a dictionary.
+
+    The function takes a string where each CSS property and its corresponding value are separated by a colon,
+    and each property-value pair is separated by a semicolon.
+    It splits the string into key-value pairs and stores them in a dictionary.
+
+    Args:
+        style (str): A string of CSS styles.
+
+    Returns:
+        dict[str, str]: A dictionary where keys are CSS property names and values are the corresponding CSS values.
+
+    Example:
+        If the input is 'color:red;background-color:blue;',
+        the output will be {'color': 'red', 'background-color': 'blue'}.
+    """
     result: dict[str, str] = {}
     key_buffer = ""
     buffer = ""
@@ -21,6 +62,23 @@ def parse_style(style: str) -> dict[str, str]:
 
 
 def style_to_string(style: dict[str, str]) -> str:
+    """
+    Converts a dictionary of CSS styles into a string representation.
+
+    The function takes a dictionary where keys are CSS property names and values are the corresponding CSS values.
+    It joins all the items in the dictionary into a string, with each key-value pair separated by a colon and each pair
+    separated by a semicolon.
+
+    Args:
+        style (dict[str, str]): A dictionary of CSS styles.
+
+    Returns:
+        str: A string representation of the CSS styles.
+
+    Example:
+        If the input is {'color': 'red', 'background-color': 'blue'},
+        the output will be 'color:red;background-color:blue;'.
+    """
     result = ";".join([f"{name}:{value}" for name, value in style.items()])
     if len(style) != 0:
         result += ";"

html_to_django/formatters/style_raw_formatter.py

@@ -1,3 +1,19 @@
+"""
+style_raw_formatter.py
+
+This module contains a function `format` that modifies a BeautifulSoup object in place.
+
+The `format` function searches for all elements with the attribute "dj-style-raw". For each found element, it parses the
+existing style attributes (if any), merges them with the styles specified in "dj-style-raw", and replaces the
+style attribute with the merged styles. The values of the "dj-style-raw" attribute are expected to be strings with pairs
+of CSS properties and values separated by semicolons (;), and each pair separated by tildes (~).
+Unlike the `style_formatter` module, this module does not insert the values into the style attribute in Django template
+variable format. Then it removes the "dj-style-raw" attribute from the element.
+
+Example:
+    If an element is <div style="color:red" dj-style-raw="background-color;blue">,
+    after processing, it becomes <div style="color:red;background-color:blue">.
+"""
 from bs4 import BeautifulSoup
 from .style_formatter import parse_style, style_to_string
 

html_to_django/formatters/unwrap_formatter.py

@@ -1,3 +1,15 @@
+"""
+unwrap_formatter.py
+
+This module contains a function `format` that modifies a BeautifulSoup object in place.
+
+The `format` function searches for all elements with the attribute "dj-unwrap". For each found element, it removes the
+element's tags but keeps its content.
+
+Example:
+    If an element is <div dj-unwrap><p>Hello, world!</p></div>,
+    after processing, it becomes <p>Hello, world!</p>.
+"""
 from bs4 import BeautifulSoup
 
 

html_to_django/formatters/var_formatter.py

@@ -1,9 +1,16 @@
 """
-Find tags with a "dj-var" attribute and replace its content with the
-value enclosed in {{ }}.
+var_formatter.py
+
+This module contains a function `format` that modifies a BeautifulSoup object in place.
+
+The `format` function searches for all elements with the attribute "dj-var". For each found element, it replaces the
+element's content with a Django template variable that has the same name as the value of the "dj-var" attribute.
+Then it removes the "dj-var" attribute from the element.
+
+Example:
+    If an element is <p dj-var="greeting">Hello, world!</p>,
+    after processing, it becomes <p>{{ greeting }}</p>.
 """
-
-
 from bs4 import BeautifulSoup