added command_entry_r entry point; updated README.md; added Attributes.md

Attributes.md

@@ -0,0 +1,3 @@
+# Attributes
+
+TODO: Add Attributes and descriptions

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
 ```

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:
+def parse_args(name: Literal["html_to_django", "html_to_django_r"]) -> Namespace:
-    parser = argparse.ArgumentParser("html_to_django")
+    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)
+
+    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.')

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"