Merge pull request #3 from davidslusser/docs

updated docs; fix model bug; rearranged project layout

Author: davidslusser

MANIFEST.in

@@ -1,5 +1,5 @@
 include README.md
 include requirements.txt
 include setup.py
-graft src/signalcontrol
+graft signalcontrol
 global-exclude *.py[co]

src/signalcontrol/migrations/__init__.py renamed to __init__.py

@@ -4,10 +4,11 @@
 About
 =====
 django-signalcontrol is a reusable django application that adds dynamic control to model signals.
-With signal_control added to a model signal, an entry for the signal is added to the SignalControl table that includes
-a boolean field to enable/disable the signal. An interface in the django admin console is provided to enable or disable
-signals individually or in bulk. When a signal is disabled it will not execute when dispatched through the receiver,
-such as post_save.
+
+
+With signal_control added to a model signal, the signal can by enabled (default) or disabled from the django admin.
+An entry for the signal is added to the SignalControl table that includes a boolean field to enable/disable the signal.
+When a signal is disabled it will not execute when dispatched through the receiver, such as post_save.
 
 See details on django-extensions features on the :ref:`Features <features>` page
 

docs/source/about.rst

@@ -7,20 +7,30 @@ Features
 This document details the features currently available in django-signalcontrol.
 
 
+Signal Detection
+----------------
+Model signals are detected automatically when django starts. Any model signal with signal_control applied will be
+detected and automatically added (if not already present) in the SignalControl database table. An info message will be
+printed when django starts if a new signal with signal_control is discovered. It will look like this:
 
-signal_control decorator
-------------------------
+``INFO: registering msg_after_my_model_save in demo with SignalControl``
+
+In this example, 'msg_after_my_model_save' is the name of the signal, and 'demo' is the name of the django app.
+
+
+The signal_control Decorator
+----------------------------
 
 SignalControl can be added to a model signal via a provided decorator. In the signal.py file, import the signalcontrol
-decorator and add to the line directly above the signal definition.
+decorator and add the signal_control decorator to the line directly above the signal definition. Example:
 
 .. code-block:: python
 
     from signalcontrol.decorators import signal_control
 
     @receiver(post_save, sender=MyCoolModel)
     @signal_control
-    def msg_my_model_two(sender, instance, created, **kwargs):
+    def msg_after_my_model_save(sender, instance, created, **kwargs):
         """ some signal """
         print("you just saved an instance of MyCoolModel")
 ..
@@ -34,3 +44,5 @@ An django admin interface for django-signalcontrol is available to set model sig
 displays all model signals that can be controlled, and lists the application, model, signal receiver and signal name.
 Additionally, full search is available and filters are available for each field.
 Signals can be enabled or disabled individually or in bulk.
+
+.. image:: images/django_admin.png

docs/source/features.rst

@@ -10,5 +10,6 @@ Contents
 
    about
    installation
+   features
    version_history
    license

docs/source/images/django_admin.png

@@ -31,15 +31,15 @@ To use django-signalcontrol in your project, add 'signalcontrol' to INSTALLED_AP
 Enabling signal control on a model signal
 -----------------------------------------
 SignalControl can be added to a model signal via a provided decorator. In the signal.py file, import the signalcontrol
-decorator and add to the line directly above the signal definition.
+decorator and add the signal_control decorator to the line directly above the signal definition. Example:
 
 .. code-block:: python
 
     from signalcontrol.decorators import signal_control
 
     @receiver(post_save, sender=MyCoolModel)
     @signal_control
-    def msg_my_model_two(sender, instance, created, **kwargs):
+    def msg_after_my_model_save(sender, instance, created, **kwargs):
         """ some signal """
         print("you just saved an instance of MyCoolModel")
 ..

docs/source/index.rst

@@ -4,13 +4,16 @@
 Version History
 ===============
 
-
-Pre-Release
------------
-
 .. csv-table::
    :header: "Release", "Details"
    :widths: 20, 100
 
+   "0.0.3", "bug fixes and project structure updates"
    "0.0.2", "added documentation"
    "0.0.1", "initial release"
+
+
+Source Code
+-----------
+
+Source code for django-signalcontrol is available on github: https://github.com/davidslusser/django-signalcontrol/

docs/source/installation.rst

@@ -1 +1 @@
-django>=2.2.9,<3.0
+django>=2.2.0

docs/source/version_history.rst

@@ -1,6 +1,6 @@
 import os
-from setuptools import setup, find_packages
-from src import signalcontrol
+from setuptools import setup
+import signalcontrol
 
 with open(os.path.join(os.path.dirname(__file__), 'README.md'), encoding='utf-8') as readme:
     README = readme.read()
@@ -15,8 +15,7 @@
     description='A django app to allow dynamic control of signals',
     long_description=README,
     long_description_content_type='text/markdown',
-    packages=find_packages(),
-    include_package_data=True,
+    packages=['signalcontrol'],
     version=version,
     license=signalcontrol.__license__,
     author=signalcontrol.__author__,

requirements.txt

@@ -7,11 +7,11 @@
 """
 
 __title__ = 'django-signalcontrol'
-__version__ = '0.0.2'
+__version__ = '0.0.3'
 __author__ = 'David Slusser'
 __email__ = 'dbslusser@gmail.com'
 __license__ = 'GPL-3.0'
 __copyright__ = 'Copyright 2020 David Slusser'
 
 
-default_app_config = 'src.signalcontrol.apps.SignalControlConfig'
+default_app_config = 'signalcontrol.apps.SignalControlConfig'

setup.py

@@ -4,5 +4,5 @@
 
 
 class SignalControlConfig(AppConfig):
-    name = 'src.signalcontrol'
+    name = 'signalcontrol'
     verbose_name = "Signal Control"

src/signalcontrol/__init__.py renamed to signalcontrol/__init__.py

@@ -1,4 +1,4 @@
-# Generated by Django 2.2.12 on 2020-04-18 20:57
+# Generated by Django 2.2.12 on 2020-04-20 21:41
 
 from django.db import migrations, models
 
@@ -15,7 +15,7 @@ class Migration(migrations.Migration):
             name='SignalControl',
             fields=[
                 ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
-                ('app_name', models.CharField(max_length=32, unique=True)),
+                ('app_name', models.CharField(max_length=32)),
                 ('model_name', models.CharField(max_length=128)),
                 ('signal_name', models.CharField(max_length=255)),
                 ('signal_type', models.CharField(max_length=32)),

src/signalcontrol/admin.py renamed to signalcontrol/admin.py

@@ -3,7 +3,7 @@
 
 class SignalControl(models.Model):
     """ table to track status of a signal used in the signal_control decorator """
-    app_name = models.CharField(max_length=32, unique=True)
+    app_name = models.CharField(max_length=32)
     model_name = models.CharField(max_length=128)
     signal_name = models.CharField(max_length=255)
     signal_type = models.CharField(max_length=32)

src/signalcontrol/apps.py renamed to signalcontrol/apps.py

@@ -1,4 +1,4 @@
-# Generated by Django 2.2.12 on 2020-04-18 20:57
+# Generated by Django 2.2.12 on 2020-04-20 21:41
 
 from django.db import migrations, models
 
@@ -15,7 +15,7 @@ class Migration(migrations.Migration):
             name='SignalControl',
             fields=[
                 ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
-                ('app_name', models.CharField(max_length=32, unique=True)),
+                ('app_name', models.CharField(max_length=32)),
                 ('model_name', models.CharField(max_length=128)),
                 ('signal_name', models.CharField(max_length=255)),
                 ('signal_type', models.CharField(max_length=32)),

src/signalcontrol/decorators.py renamed to signalcontrol/decorators.py

@@ -3,7 +3,7 @@
 
 class SignalControl(models.Model):
     """ table to track status of a signal used in the signal_control decorator """
-    app_name = models.CharField(max_length=32, unique=True)
+    app_name = models.CharField(max_length=32)
     model_name = models.CharField(max_length=128)
     signal_name = models.CharField(max_length=255)
     signal_type = models.CharField(max_length=32)