docs: add intro

README.md

@@ -4,7 +4,7 @@
 
 <h1 align="center">
   <a href="https://www.django-unicorn.com/">Falco</a>
-  <p>The toolkit for a better django development experience</p>
+  <p>An opinionated toolkit for a modern Django development experience</p>
 </h1>
 
 [![documentation](https://github.com/Tobi-De/falco/actions/workflows/documentation.yml/badge.svg)](https://github.com/Tobi-De/falco/actions/workflows/documentation.yml)
@@ -19,7 +19,7 @@
 
 <!-- start-docs -->
 
-Intro here....
+Falco is a Django-centric toolkit designed to enhance the development experience. The CLI offers commands for initiating new projects, generating simple CRUD views for rapid prototyping, and more. Additionally, it provides a collection of guides specifically tailored to address common issues in web development, focusing on Django projects.
 
 <!-- [![Read the full documentation](https://img.shields.io/badge/Read%20The%20full%20Documentation-blue?style=for-the-badge&logo=ReadTheDocs)](https://falco.oluwatobi.dev) -->
 

docs/guides/tips_and_extra.rst

@@ -23,6 +23,13 @@ Lifecycle not signals
 ---------------------
 
 
+Better use personal info fields
+--------------------------------
+
+The project also includes `django-improved-user <https://django-improved-user.readthedocs.io/en/latest/index.html>`__ which replaces the common ``first_name`` and ``last_name`` used for user details with ``full_name``
+and the ``short_name`` fields. If you want to know the reasoning behind this, read the `project rationale <https://django-improved-user.readthedocs.io/en/latest/rationale.html>`__.
+Currently, the latest version of ``django-improved-user`` that works without problems is an alpha version (v2.0a2). This can be annoying
+
 Avoid huge apps for large projects
 ----------------------------------
 
@@ -31,6 +38,18 @@ Generate admin
 
 https://django-extensions.readthedocs.io/en/latest/admin_generator.html
 
+.. code-block:: bash
+
+    python manage.py admin_generator your_app | tail -n +2 > your_project/your_app/admin.py
+
+As a hatch script
+
+.. code-block:: toml
+
+    [tool.hatch.envs.default.scripts]
+    admin = "python manage.py admin_generator {args} | tail -n +2 > your_project/{args}/admin.py"
+
+
 Auto Fill forms
 ---------------
 

docs/the_cli/start_project.rst

@@ -39,11 +39,12 @@ Features
 - Serve static files with `Whitenoise <https://whitenoise.evans.io/en/latest/>`_
 - Default integration with `pre-commit <https://github.com/pre-commit/pre-commit>`_ for identifying simple issues before submission to code review
 - Dependency management using `hatch <https://github.com/pypa/hatch>`_
+- Playground file for local testing with `dj-notebook <https://github.com/pydanny/dj-notebook>`_.
 
 .. tip::
 
    If you are using a jetbrains IDE, there is an extension that add support for htmx, you can find it `here <https://plugins.jetbrains.com/plugin/20588-htmx-support>`_.
-   If you use `alpinejs <https://alpinejs.dev/>` there is also for it via `this extension <https://plugins.jetbrains.com/plugin/15251-alpine-js-support>`_.
+   If you use `alpinejs <https://alpinejs.dev/>`_ there is also for it via `this extension <https://plugins.jetbrains.com/plugin/15251-alpine-js-support>`_.
 
 
 Project Structure
@@ -57,20 +58,22 @@ in your generated project.
 
 
 Login via email instead of username
------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 I completely removed the ``username`` field from the ``User`` model and replaced it with the ``email`` field as the user unique identifier.
 This ``email`` field is what I configured as the login field via `django-allauth <https://github.com/pennersr/django-allauth>`__. More often then not when I create a new django project
 I need to use something other than the ``username`` field provided by django as the unique identifier of the user, and the ``username`` field
 just becomes an annoyance to deal with. It is also more common nowadays for modern web and mobile applications to rely on a unique identifier
 such as an email address or phone number instead of a username.
-The project also includes `django-improved-user <https://django-improved-user.readthedocs.io/en/latest/index.html>`__ which replaces the common ``first_name`` and ``last_name`` used for user details with ``full_name``
-and the ``short_name`` fields. If you want to know the reasoning behind this, read the `project rationale <https://django-improved-user.readthedocs.io/en/latest/rationale.html>`__.
-Currently, the latest version of ``django-improved-user`` that works without problems is an alpha version (v2.0a2). This can be annoying
+
 to deal with when updating dependencies, you can get the same result as I just described with the django-authtools package.
 
-!!! Note “Don’t ask for what you don’t need”
-Make sure you need ``first_name`` - ``last_name`` or ``short_name`` - ``full_name`` before asking your users for this information.
+https://gdpr.eu/compliance/
+
+.. admonition:: Don’t ask for what you don’t need
+   :class: note
+
+   Make sure you need ``first_name`` - ``last_name`` or ``short_name`` - ``full_name`` before asking your users for this information.
 
 ::
 
@@ -82,11 +85,10 @@ Make sure you need ``first_name`` - ``last_name`` or ``short_name`` - ``full_nam
 If on the other hand you don’t agree with what I just wrote or for the particular project you are currently working on
 my configuration doesn’t work for you, removing django-improved-user should be an easy change.
 
-First update the ``User`` models to inherit from django ``AbstractUser`` instead of the django-improved-ser one.
+First update the ``User`` models to look exactly like in the code below.
 
-.. code:: python
-
-   # users/models.py
+.. code-block:: python
+   :caption: users/models.py
 
    from django.contrib.auth.models import AbstractUser
 
@@ -98,23 +100,17 @@ With that you should be good to go, if you want something a little more complete
 code from the `cookiecutter-django users app <https://github.com/cookiecutter/cookiecutter-django/tree/master/%7B%7Bcookiecutter.project_slug%7D%7D/%7B%7Bcookiecutter.project_slug%7D%7D/users>`__.
 
 HTMX and template partials
---------------------------
-
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Browser reload
---------------
-
-Debug Toolbar
--------------
 
 
 DjangoFastDev
--------------
+^^^^^^^^^^^^^
 
 Occasionally you may see a ``FastDevVariableDoesNotExist`` error, this exception is thrown during template rendering
 by `django-fastdev <https://github.com/boxed/django-fastdev>`__ when you try to access a variable that is not defined in the context
 context of the view associated with that template. This is intended to help you avoid typos and small errors that will
-have you scratching your head for hours, read the project `readme <https://github.com/boxed/django-fastdev#django-fastdev>`__ if you want more reasons
+have you scratching your head for hours, read the project `readme <https://github.com/boxed/django-fastdev#django-fastdev>`_ if you want more reasons
 to why it make sense to use it. But since this can be annoying for some people, you can disable it by removing ``django-fastdev``
 entirely or by commenting out the *django-fastdev* application in the ``settings.py`` file.
 
@@ -125,36 +121,18 @@ entirely or by commenting out the *django-fastdev* application in the ``settings
        # 'django_fastdev',
    ]
 
-Dependencies management
------------------------
-
-If you are using poetry then you probably already knows what to do, using poetry is pretty straightforward and that’s why I like it.
-With poetry the simplest workflow looks something like this:
+Dj Notebook
+^^^^^^^^^^^
 
-.. code:: shell
+This is a recent addition to the project, It is basically using your django shell in a jupyter notebook. There is a ``playground.ipynb`` at the root of the generated
+project, it configured with dj-notebook, I personnally find myself using it to keep some query in text so that I don't have to retype them everyone or search
+through my command line history. You need to alwas run the first setting before anything to setup django. Also keep in mind that is does not automatically pickup
+files changes so you'll have to restart the kernel to see changes.
+If you a primer on jupyter notebook, you can find one `here <https://www.dataquest.io/blog/jupyter-notebook-tutorial/>`_.
 
-   poetry install
-   poetry add package_name
-   poetry remove package_name
 
-!!! Note “Updating your dependencies”
-I recommend the `poetry-plugin-up <https://github.com/MousaZeidBaker/poetry-plugin-up>`__ to easily update your dependencies.
-I used to include `poetryup <https://github.com/MousaZeidBaker/poetryup>`__ in the project template, but that has been deprecated
-in favor of the new `up plugin <https://github.com/MousaZeidBaker/poetryup>`__.
-
-If on the other hand you choose to remove poetry using the ```cuzzy remove-poetry`` <https://tobi-de.github.io/falco/usage/#cuzzy-remove-poetry>`__ and additionally
-created a virtualenv with the ``-c`` option, then I’ve added a few things that might be useful to you.
-
-The ``pyproject.toml`` file
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-When I first started using poetry I thought this file was a poetry specific thing, but it turns out that it is not. The ``pyproject.toml`` file is a
-python standard introduced to unify and simplify python project packaging and configurations.
-The pip documentation gives much more details on this than I can cover here, so I will just link to it `here <https://pip.pypa.io/en/stable/reference/build-system/pyproject-toml/>`__.
-A loot of tools in the python ecosystem support it and it seems this is what we are going to be using in the future so I’ve kept it.
-
-Hatch
-~~~~~
+Hatch for dependencies management
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Installed at the same time as ``pip-tools``, `Hatch <https://hatch.pypa.io/latest/>`__ is the build system specified in the ``pyproject.toml`` file. Since you are probably
 not going to package and publish your django project you don’t really need it, but ``pip-tools`` does need a build system defined
@@ -177,13 +155,25 @@ Just run
 Read the `hatch documentation <https://hatch.pypa.io/latest/>`__ for more infos.
 
 
-Static and media files
-----------------------
 
+The ``pyproject.toml`` file
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``pyproject.toml`` file is a python standard introduced to unify and simplify python project packaging and configurations.
+The pip documentation gives much more details on this than I can cover here, so I will just link to it `here <https://pip.pypa.io/en/stable/reference/build-system/pyproject-toml/>`__.
+A lot of tools (including hatch) in the python ecosystem support it and it seems this is what we are going to be using in the future so that's why I choose it.
 
-Switch to bootstrap5
---------------------
+
+Tailwind CSS
+^^^^^^^^^^^^
 
 
 Alternative starters
 --------------------
+
+https://github.com/cookiecutter/cookiecutter-django
+https://github.com/oliverandrich/django-hatch-startproject
+https://github.com/oliverandrich/django-poetry-startproject
+https://github.com/jefftriplett/django-startproject
+https://github.com/wsvincent/djangox
+https://github.com/wemake-services/wemake-django-template

pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 [project]
 name = "falco-cli"
 dynamic = ["version"]
-description = ''
+description = 'Enhance your Django developer experience: CLI and Guides for the Modern Developer.'
 readme = "README.md"
 requires-python = ">=3.10"
 license = "MIT"

src/falco/commands/model_crud.py

@@ -42,7 +42,8 @@ class DjangoModelWithContext(DjangoModel):
 model_name = lambda model: model.__name__
 model_fields_names = lambda model: [field.name for field in model._meta.fields if field.name not in exclude_fields]
 model_fields_verbose_names = lambda model: [field.verbose_name for field in model._meta.fields if field.name not in exclude_fields]
-print([{{"model_name": model_name(model), "model_fields_names": model_fields_names(model), "model_fields_verbose_names": model_fields_verbose_names(model)}} for model in models])
+get_model_dict = lambda model: {{"model_name": model_name(model), "model_fields_names": model_fields_names(model), "model_fields_verbose_names": model_fields_verbose_names(model)}}
+print([get_model_dict(model) for model in models])
 """
 
 app_path_and_templates_dir_code = """

src/falco/commands/work.py

@@ -6,8 +6,8 @@
 import cappa
 from dotenv import load_dotenv
 from honcho.manager import Manager as HonchoManager
-from honcho.process import Process as HonchoProcess
 from honcho.process import Popen as HonchoPopen
+from honcho.process import Process as HonchoProcess
 
 
 try:
@@ -24,7 +24,6 @@ class Popen(HonchoPopen):
     def __init__(self, cmd, **kwargs):
         kwargs.setdefault("start_new_session", False)
         super().__init__(cmd, **kwargs)
-        print(self.pid)
 
 
 class Process(HonchoProcess):
@@ -57,9 +56,7 @@ def __call__(self) -> None:
 
         with suppress(FileNotFoundError):
             pyproject_config = read_toml(Path("pyproject.toml"))
-            user_commands = (
-                pyproject_config.get("tool", {}).get("falco", {}).get("work", {})
-            )
+            user_commands = pyproject_config.get("tool", {}).get("falco", {}).get("work", {})
             commands = commands | user_commands
 
         manager = Manager()