Documented overriding create_historical_record()

...as a more fine-grained alternative to the other ways of disabling
historical record creation.

Author: ddabble

docs/disabling_history.rst

@@ -43,6 +43,29 @@ See some examples below:
         Poll.objects.create(question="ignore this")
         Poll.objects.create(question="what's up?")
 
+Overriding ``create_historical_record()``
+-----------------------------------------
+
+For even more fine-grained control, you can subclass ``HistoricalRecords`` and override
+its ``create_historical_record()`` method, for example like this:
+
+.. code-block:: python
+
+    class CustomHistoricalRecords(HistoricalRecords):
+        def create_historical_record(
+            self, instance: models.Model, history_type: str, *args, **kwargs
+        ) -> None:
+        # Don't create records for "ignore" polls that are being deleted
+        if "ignore" in poll.question and history_type == "-":
+            return
+
+        super().create_historical_record(instance, history_type, *args, **kwargs)
+
+
+    class Poll(models.Model):
+        # ...
+        history = CustomHistoricalRecords()
+
 The ``SIMPLE_HISTORY_ENABLED`` setting
 --------------------------------------
 

simple_history/models.py

@@ -768,7 +768,9 @@ def create_historical_record_m2ms(self, history_instance, instance):
                 field=field,
             )
 
-    def create_historical_record(self, instance, history_type, using=None):
+    def create_historical_record(
+        self, instance: models.Model, history_type: str, using: str = None
+    ) -> None:
         using = using if self.use_base_model_db else None
         history_date = getattr(instance, "_history_date", timezone.now())
         history_user = self.get_history_user(instance)