Add documentation for custom model actions

- Add plugin development guide for registering custom actions
- Update admin permissions docs to mention custom actions UI
- Add docstrings to ModelAction and register_model_actions

docs/administration/permissions.md

@@ -20,7 +20,9 @@ There are four core actions that can be permitted for each type of object within
 * **Change** - Modify an existing object
 * **Delete** - Delete an existing object
 
-In addition to these, permissions can also grant custom actions that may be required by a specific model or plugin. For example, the `run` permission for scripts allows a user to execute custom scripts. These can be specified when granting a permission in the "additional actions" field.
+In addition to these, permissions can also grant custom actions that may be required by a specific model or plugin. For example, the `sync` action for data sources allows a user to synchronize data from a remote source, and the `render_config` action for devices and virtual machines allows rendering configuration templates.
+
+Some models have registered custom actions that appear as checkboxes when creating or editing a permission. These are grouped by model under "Custom actions" in the permission form. Additional custom actions (such as those not yet registered or for backwards compatibility) can be entered manually in the "Additional actions" field.
 
 !!! note
     Internally, all actions granted by a permission (both built-in and custom) are stored as strings in an array field named `actions`.

docs/plugins/development/permissions.md

@@ -0,0 +1,36 @@
+# Custom Model Actions
+
+Plugins can register custom permission actions for their models. These actions appear as checkboxes in the ObjectPermission form, making it easy for administrators to grant or restrict access to plugin-specific functionality without manually entering action names.
+
+For example, a plugin might define a "sync" action for a model that syncs data from an external source, or a "bypass" action that allows users to bypass certain restrictions.
+
+## Registering Model Actions
+
+To register custom actions for a model, call `register_model_actions()` in your plugin's `ready()` method:
+
+```python
+# __init__.py
+from netbox.plugins import PluginConfig
+
+class MyPluginConfig(PluginConfig):
+    name = 'my_plugin'
+    # ...
+
+    def ready(self):
+        super().ready()
+        from utilities.permissions import ModelAction, register_model_actions
+        from .models import MyModel
+
+        register_model_actions(MyModel, [
+            ModelAction('sync', help_text='Synchronize data from external source'),
+            ModelAction('export', help_text='Export data to external system'),
+        ])
+
+config = MyPluginConfig
+```
+
+Once registered, these actions will appear grouped under your model's name when creating or editing an ObjectPermission that includes your model as an object type.
+
+::: utilities.permissions.ModelAction
+
+::: utilities.permissions.register_model_actions

mkdocs.yml

@@ -151,6 +151,7 @@ nav:
             - Filters & Filter Sets: 'plugins/development/filtersets.md'
             - Search: 'plugins/development/search.md'
             - Event Types: 'plugins/development/event-types.md'
+            - Permissions: 'plugins/development/permissions.md'
             - Data Backends: 'plugins/development/data-backends.md'
             - Webhooks: 'plugins/development/webhooks.md'
             - User Interface: 'plugins/development/user-interface.md'

netbox/utilities/permissions.py

@@ -21,6 +21,13 @@ __all__ = (
 
 @dataclass
 class ModelAction:
+    """
+    Represents a custom permission action for a model.
+
+    Attributes:
+        name: The action identifier (e.g. 'sync', 'render_config')
+        help_text: Optional description displayed in the ObjectPermission form
+    """
     name: str
     help_text: str = ''
 
@@ -34,6 +41,14 @@ class ModelAction:
 
 
 def register_model_actions(model: type[Model], actions: list[ModelAction | str]):
+    """
+    Register custom permission actions for a model. These actions will appear as
+    checkboxes in the ObjectPermission form when the model is selected.
+
+    Args:
+        model: The model class to register actions for
+        actions: A list of ModelAction instances or action name strings
+    """
     label = f'{model._meta.app_label}.{model._meta.model_name}'
     for action in actions:
         if isinstance(action, str):