From dd552264559c968c94a725c9558a4fd01cd039c4 Mon Sep 17 00:00:00 2001
From: jeremystretch <jstretch@ns1.com>
Date: Wed, 19 Jan 2022 16:44:18 -0500
Subject: [PATCH] Draft documentation for model features

---
 docs/plugins/development/index.md          |  3 ++
 docs/plugins/development/model-features.md | 37 ++++++++++++++++++++++
 mkdocs.yml                                 | 18 ++++++++++-
 netbox/netbox/models/features.py           | 24 +++++++++++---
 4 files changed, 76 insertions(+), 6 deletions(-)
 create mode 100644 docs/plugins/development/index.md
 create mode 100644 docs/plugins/development/model-features.md

diff --git a/docs/plugins/development/index.md b/docs/plugins/development/index.md
new file mode 100644
index 000000000..31ce5fc2e
--- /dev/null
+++ b/docs/plugins/development/index.md
@@ -0,0 +1,3 @@
+# Plugins Development
+
+TODO
diff --git a/docs/plugins/development/model-features.md b/docs/plugins/development/model-features.md
new file mode 100644
index 000000000..83f9b4205
--- /dev/null
+++ b/docs/plugins/development/model-features.md
@@ -0,0 +1,37 @@
+# Model Features
+
+Plugin models can leverage certain NetBox features by inheriting from designated Python classes (documented below), defined in `netbox.models.features`. These classes perform two crucial functions:
+
+1. Apply any fields, methods, or attributes necessary to the operation of the feature
+2. Register the model with NetBox as utilizing the feature
+
+For example, to enable support for tags in a plugin model, it should inherit from `TagsMixin`:
+
+```python
+# models.py
+from django.db.models import models
+from netbox.models.features import TagsMixin
+
+class MyModel(TagsMixin, models.Model):
+    foo = models.CharField()
+    ...
+```
+
+This will ensure that TaggableManager is applied to the model, and that the model is registered with NetBox as taggable.
+
+!!! note
+    Please note that only the classes which appear in this documentation are currently supported. Although other classes may be present within the `features` module, they are not yet supported for use by plugins.
+
+::: netbox.models.features.CustomLinksMixin
+
+::: netbox.models.features.CustomFieldsMixin
+
+::: netbox.models.features.ExportTemplatesMixin
+
+::: netbox.models.features.JobResultsMixin
+
+::: netbox.models.features.JournalingMixin
+
+::: netbox.models.features.TagsMixin
+
+::: netbox.models.features.WebhooksMixin
diff --git a/mkdocs.yml b/mkdocs.yml
index f89bdaea7..764a04c86 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -16,6 +16,19 @@ theme:
       toggle:
         icon: material/lightbulb
         name: Switch to Light Mode
+plugins:
+  - mkdocstrings:
+      handlers:
+        python:
+          setup_commands:
+            - import os
+            - import django
+            - os.environ.setdefault("DJANGO_SETTINGS_MODULE", "netbox.settings")
+            - django.setup()
+          rendering:
+            show_root_heading: true
+            show_root_full_path: false
+            show_root_toc_entry: false
 extra:
   social:
     - icon: fontawesome/brands/github
@@ -84,7 +97,10 @@ nav:
         - Webhooks: 'additional-features/webhooks.md'
     - Plugins:
         - Using Plugins: 'plugins/index.md'
-        - Developing Plugins: 'plugins/development.md'
+        - Developing Plugins:
+            - Introduction: 'plugins/development/index.md'
+            - Model Features: 'plugins/development/model-features.md'
+        - Developing Plugins (Old): 'plugins/development.md'
     - Administration:
         - Authentication: 'administration/authentication.md'
         - Permissions: 'administration/permissions.md'
diff --git a/netbox/netbox/models/features.py b/netbox/netbox/models/features.py
index ed0e481ad..7865e3c8a 100644
--- a/netbox/netbox/models/features.py
+++ b/netbox/netbox/models/features.py
@@ -93,13 +93,25 @@ class CustomFieldsMixin(models.Model):
     @property
     def cf(self):
         """
-        Convenience wrapper for custom field data.
+        A pass-through convenience alias for accessing `custom_field_data` (read-only).
+
+        ```python
+        >>> tenant = Tenant.objects.first()
+        >>> tenant.cf
+        {'cust_id': 'CYB01'}
+        ```
         """
         return self.custom_field_data
 
     def get_custom_fields(self):
         """
-        Return a dictionary of custom fields for a single object in the form {<field>: value}.
+        Return a dictionary of custom fields for a single object in the form `{field: value}`.
+
+        ```python
+        >>> tenant = Tenant.objects.first()
+        >>> tenant.get_custom_fields()
+        {<CustomField: Customer ID>: 'CYB01'}
+        ```
         """
         from extras.models import CustomField
 
@@ -165,7 +177,7 @@ class ExportTemplatesMixin(models.Model):
 
 class JobResultsMixin(models.Model):
     """
-    Enable the assignment of JobResults to a model.
+    Enables support for job results.
     """
     class Meta:
         abstract = True
@@ -173,7 +185,8 @@ class JobResultsMixin(models.Model):
 
 class JournalingMixin(models.Model):
     """
-    Enables support for JournalEntry assignment.
+    Enables support for object journaling. Adds a generic relation (`journal_entries`)
+    to NetBox's JournalEntry model.
     """
     journal_entries = GenericRelation(
         to='extras.JournalEntry',
@@ -187,7 +200,8 @@ class JournalingMixin(models.Model):
 
 class TagsMixin(models.Model):
     """
-    Enable the assignment of Tags to a model.
+    Enables support for tag assignment. Assigned tags can be managed via the `tags` attribute,
+    which is a `TaggableManager` instance.
     """
     tags = TaggableManager(
         through='extras.TaggedItem'