From 6274a76e735ba0791fbd6b0c99c43c15d7d9a3e6 Mon Sep 17 00:00:00 2001
From: truePhilipp <philipp@mayr.software>
Date: Mon, 6 May 2024 23:35:12 +0200
Subject: [PATCH] added command_entry_r entry point; updated README.md; added
 Attributes.md

---
 Attributes.md               |  3 +++
 README.md                   | 45 +++++++++++++++++++++++++------------
 html_to_django/converter.py | 37 +++++++++++++++++++++++-------
 pyproject.toml              |  1 +
 4 files changed, 64 insertions(+), 22 deletions(-)
 create mode 100644 Attributes.md

diff --git a/Attributes.md b/Attributes.md
new file mode 100644
index 0000000..2b00de0
--- /dev/null
+++ b/Attributes.md
@@ -0,0 +1,3 @@
+# Attributes
+
+TODO: Add Attributes and descriptions
\ No newline at end of file
diff --git a/README.md b/README.md
index 7f092a5..c1cbb4b 100644
--- a/README.md
+++ b/README.md
@@ -1,32 +1,49 @@
-HTML To Django
-===
+# HTML To Django
 
 ![tests workflow](https://github.com/truePhilipp/html_to_django/actions/workflows/tests.yml/badge.svg)
 ![stylecheck workflow](https://github.com/truePhilipp/html_to_django/actions/workflows/stylecheck.yml/badge.svg)
 
-Convert HTML files with special syntax to Django template files.
+Converts HTML files with special attributes to Django templates.
 
-Installation
----
+
+# Installation
 TODO: pip install instructions
 
-Usage
----
+
+# Usage
 ```bash
-html_to_django <path to file or folder to convert>
+html_to_django [-h] [-r] path
+```
+Use `-r` to replace the original files, instead of creating new ones.
+By default, new ones are created in place next to the existing files, with the extension `.n.html`.
+
+You can also use the `html_to_django_r` command if you are unable to pass the `-r` parameter
+(e.g. with the Bootstrap Studio "Export Script" setting)
+
+## Attributes
+To add Django template tags to your HTML files, you need to add special attributes to your HTML tags like this:
+```html
+<div dj-for="user in users">
+    <p>{{ user.name }}</p>
+</div>
+```
+This will be converted to:
+```html
+{% for user in users %}
+<p>{{ user.name }}</p>
+{% endfor %}
 ```
 
-Development
-===
+A complete list can be found in the [Attributes.md](Attributes.md) file.
 
-Testing
----
+
+# Development
+## Testing
 ```bash
 python -m unittest discover tests --verbose
 ```
 
-Stylechecks
----
+## Stylechecks
 ```bash
 mypy --strict html_to_django
 ```
diff --git a/html_to_django/converter.py b/html_to_django/converter.py
index f99a823..fe97eea 100644
--- a/html_to_django/converter.py
+++ b/html_to_django/converter.py
@@ -1,7 +1,8 @@
 import bs4
 import sys
 import os
-import argparse
+from typing import Literal
+from argparse import ArgumentParser, RawDescriptionHelpFormatter, Namespace
 from glob import glob
 from .formatters import formatters
 
@@ -40,20 +41,29 @@ def convert_dir(path: str, overwrite: bool = False) -> None:
         convert_file(filepath, overwrite)
 
 
-def parse_args() -> argparse.Namespace:
-    parser = argparse.ArgumentParser("html_to_django")
+def parse_args(name: Literal["html_to_django", "html_to_django_r"]) -> Namespace:
+    description = "Converts HTML files with special attributes to Django templates."
+    if name == "html_to_django_r":
+        description = ("Info: This command is identical to html_to_django, but will always replace the input file(s)!"
+                       f"\n\n{description}")
+
+    parser = ArgumentParser(name, description=description, formatter_class=RawDescriptionHelpFormatter)
+
     parser.add_argument("path", help="""
     The path to a file (or folder of files) to be converted.
-    In case a folder is passed, ALL html files in it (recursivly) will be converted.
+    In case a folder is passed, ALL html files in it (recursively) will be converted.
     """, type=str)
-    parser.add_argument("-r", "--replace", help="""
-    Replace the input file(s).
-    """, action='store_true')
+
+    if name == "html_to_django":
+        parser.add_argument("-r", "--replace", help="""
+        Replace the input file(s).
+        """, action='store_true')
+
     return parser.parse_args()
 
 
 def command_entry() -> None:
-    args = parse_args()
+    args = parse_args("html_to_django")
     path = os.path.abspath(args.path)
     if os.path.isdir(path):
         convert_dir(path, args.replace)
@@ -61,3 +71,14 @@ def command_entry() -> None:
         convert_file(path, args.replace)
     else:
         sys.exit(f'The path "{path}" does not exist.')
+
+
+def command_entry_r() -> None:
+    args = parse_args("html_to_django_r")
+    path = os.path.abspath(args.path)
+    if os.path.isdir(path):
+        convert_dir(path, True)
+    elif os.path.isfile(path):
+        convert_file(path, True)
+    else:
+        sys.exit(f'The path "{path}" does not exist.')
diff --git a/pyproject.toml b/pyproject.toml
index cb69ca1..9d1eb3e 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -38,6 +38,7 @@ Issues = "https://github.com/truePhilipp/html_to_django/issues"
 
 [project.scripts]
 html_to_django = "html_to_django.converter:command_entry"
+html_to_django_r = "html_to_django.converter:command_entry_r"
 
 [tool.hatch.version]
 path = "html_to_django/__about__.py"
\ No newline at end of file