improve docs and naming of helper methods on the settings base model

README.rst

@@ -32,12 +32,18 @@ implementation that you can use, the abstract model ``SettingsModel`` can be use
 construct your own settings model(s), and things like webserver restarts are handled in
 the abstract model class.
 
-**The Problem**: Sometimes you want to build an app that can run on an arbitrary piece
-of equipment, and things like timezone, hostname, or SMTP settings may need to be
+**The Problem**: Sometimes you want to build an app that can be managed by
+non-developers, and things like timezone, hostname, or SMTP settings may need to be
 editable from the UI.
 
 **The Solution**: This app implements a base ``SettingsModel`` class that allows you to
-expose settings to a user interface via the database.
+expose settings to a user interface via the database. It writes these stub settings to
+separate files which you try/include at the end of your main settings file. This way
+you have sensible defaults, but when the user created/edits a model file in the UI,
+those settings override. There is a mechanism to touch the ``wsgi.py``/``manage.py``
+files when saving, so the only thing left to do is either configure your web server to
+watch those files and reboot when they are touched, or use a tool like ``incrond`` to
+watch those files and trigger your webserver to reboot when they are touched.
 
 
 How to Use

settings_model/__init__.py

@@ -1,2 +1,2 @@
-__version__ = "0.4.0"
+__version__ = "0.5.0"
 default_app_config = "settings_model.apps.CustomConfig"

settings_model/models.py

@@ -142,11 +142,11 @@ def save(self, *args, **kwargs):
         # if we are saving an active settings instance, reboot the web server
         if self.is_active:
             if reboot:
-                transaction.on_commit(lambda: self.write_and_reboot())
+                transaction.on_commit(lambda: self.write_and_signal_reboot())
         return super().save(*args, **kwargs)
 
     @staticmethod
-    def touch_reboot_files():
+    def signal_reboot():
         """
         Find and touch the reboot files to signal the server to restart.
         """
@@ -176,16 +176,16 @@ def touch_reboot_files():
             else:
                 print("settings_model:  - {} (skipped, doesn't exist)".format(f))
 
-    def write_and_reboot(self, commit=True):
+    def write_and_signal_reboot(self, commit=True):
         """
-        Commit the configuration to disk and call `touch_reboot_files`.
+        Commit the configuration to disk and call `signal_reboot`.
         """
         if commit:
             print("settings_model: committing config to disk...")
             self.write_settings()
 
         # signal reboot
-        self.touch_reboot_files()
+        self.signal_reboot()
 
 
 class Settings(SettingsModel):

settings_model/tests.py

@@ -36,7 +36,7 @@ def test_change_settings(self):
         self.assertEqual(self.settings.debug_mode, not old_debug)
 
     def test_write_and_reboot(self):
-        self.settings.write_and_reboot()
+        self.settings.write_and_signal_reboot()
 
 
 class SettingsModelAdminTestCase(TestCase):