feat: sync-dotenv Closes #71

docs/install.rst

@@ -3,15 +3,7 @@
 Installation
 ============
 
-.. rst-class:: lead
-
-   Install the **falco** theme as a Python package.
-
-----
-
-
-Falco is conveniently available as a Python package on PyPI and can be easily
-installed using pip.
+Falco is available on PyPI and can be installed with pip or your favorite Python package manager.
 
 .. code-block:: shell
 
@@ -24,11 +16,13 @@ Next Up
 .. grid:: 2
 
     .. grid-item-card:: The CLI
-        :link: /the_cli/
+      :link: /the_cli/
 
-        Always have a tab open to the official Django documentation. It is the best source of information.
+      The documentation for the ``falco`` command line interface (CLI).
 
     .. grid-item-card:: Guides
-        :link: /guides/
+      :link: /guides/
+
+      A collection of guides on common web development topics and how to solve them in django.
 
-        Another tab you should always have open is the HTMX documentation.
+

docs/the_cli/rm_migrations.rst

@@ -1,5 +1,5 @@
-Clean migrations in dev
-=======================
+Clean all migrations
+====================
 
 .. figure:: ../images/rm-migrations.svg
 

docs/the_cli/sync_dotenv.rst

@@ -5,12 +5,24 @@ Keep the .env and .env.template in sync
 .. figure:: ../images/sync-dotenv.svg
 
 
-Running this will create a new ``.env`` by filling the file with the keys and values from the following options:
+When you run the ``sync-dotenv`` command, it performs the following steps:
 
-1. a ``env.template`` file, used if it exists
-2. a ``DEFAULT_VALUES`` dictionary, internal to the ``falco`` package, contains some default for common
-   keys, ``DJANGO_DEBUG``, ``DJANGO_SECRET_KEY``, etc.
-3. a ``.env`` file, used if it exists
+#. It reads the values from the ``.env.template`` file, a set of default values (see below), and the ``.env`` file, in that order. If the same key is present in multiple sources, the value from the later source is used.
+#. If the ``--fill-missing`` option is provided, it will prompt you to fill in any values that are currently empty.
+#. It sorts the configuration keys alphabetically.
+#. It empties the ``.env`` file and writes the new configuration values to it. Each key-value pair is written on a new line, with the format ``KEY=VALUE``.
+#. It empties the ``.env.template`` file and writes the new configuration keys to it. If a key was originally present in the ``.env.template`` file, its value is preserved; otherwise, the value is left empty.
 
-The order defines the priority of the values that are used, which means that the values contained in your
-original ``.env`` file are preserved if the file exists.
+
+**Default Values**
+
+The command uses the following default values:
+
+- ``DJANGO_DEBUG``: ``True``
+- ``DJANGO_SECRET_KEY``: A randomly generated secure token.
+- ``DJANGO_ALLOWED_HOSTS``: ``*``
+- ``DATABASE_URL``: ``postgres:///<project_name>``, where ``<project_name>`` is the name of the current directory.
+- ``DJANGO_SUPERUSER_EMAIL``:
+- ``DJANGO_SUPERUSER_PASSWORD``:
+
+These values are used if they are not already specified in the `.env` or `.env.template` files.

src/falco/commands/sync_dotenv.py

@@ -23,45 +23,60 @@ class SyncDotenv:
             help="Prompt to fill missing values.",
         ),
     ]
-    project_name: Annotated[
-        str, cappa.Arg(parse=get_current_dir_as_project_name, hidden=True)
-    ]
 
     def __call__(
-        self,
+        self, project_name: Annotated[str, cappa.Dep(get_current_dir_as_project_name)]
     ):
+        dotenv_file = Path(".env")
+        dotenv_template_file = Path(".env.template")
+
         default_values = {
             "DJANGO_DEBUG": True,
             "DJANGO_SECRET_KEY": secrets.token_urlsafe(64),
             "DJANGO_ALLOWED_HOSTS": "*",
-            "DATABASE_URL": f"postgres:///{self.project_name}",
+            "DATABASE_URL": f"postgres:///{project_name}",
             "DJANGO_SUPERUSER_EMAIL": "",
             "DJANGO_SUPERUSER_PASSWORD": "",
         }
 
         config = {
-            **dotenv_values(".env.template"),
+            **dotenv_values(dotenv_template_file),
             **default_values,
-            **dotenv_values(".env"),
+            **dotenv_values(dotenv_file),
         }
 
         if self.fill_missing:
             for key, value in config.items():
                 if not value:
                     config[key] = Prompt.ask(f"{key}")
 
-        # create .env file
-        env_file = Path(".env")
-        env_file.write_text("")
+        sorted_config = dict(sorted(config.items(), key=lambda x: str(x[0])))
 
-        # set env values
-        for key, value in config.items():
+        # empty .env and write values
+        dotenv_file.write_text("")
+        for key, value in sorted_config.items():
             set_key(
-                env_file,
+                dotenv_file,
                 key,
                 value,
                 quote_mode="never",
                 export=False,
                 encoding="utf-8",
             )
-        rich_print(f"[green] {env_file} file generated[/green]")
+
+        # empty and write to .env.template file
+        original_values = dotenv_values(dotenv_template_file)
+        dotenv_template_file.write_text("")
+        for key, value in sorted_config.items():
+            set_key(
+                dotenv_template_file,
+                key,
+                original_values.get(key, ""),
+                quote_mode="never",
+                export=False,
+                encoding="utf-8",
+            )
+
+        rich_print(
+            f"[green] {dotenv_file} and {dotenv_template_file} synchronised [/green]"
+        )