From dd552264559c968c94a725c9558a4fd01cd039c4 Mon Sep 17 00:00:00 2001 From: jeremystretch 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 {: 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() + {: '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'