Clean up model & registry documentation

netbox-community · Feb 20, 2023 · 6850c1a · 6850c1a
1 parent 76b584e
commit 6850c1a
Show file tree

Hide file tree

Showing 6 changed files with 134 additions and 43 deletions.
diff --git a/docs/development/application-registry.md b/docs/development/application-registry.md
@@ -8,6 +8,14 @@ The registry can be inspected by importing `registry` from `extras.registry`.
 
 ## Stores
 
+### `data_backends`
+
+A dictionary mapping data backend types to their respective classes. These are used to interact with [remote data sources](../models/core/datasource.md).
+
+### `denormalized_fields`
+
+Stores registration made using `netbox.denormalized.register()`. For each model, a list of related models and their field mappings is maintained to facilitate automatic updates.
+
 ### `model_features`
 
 A dictionary of particular features (e.g. custom fields) mapped to the NetBox models which support them, arranged by app. For example:
@@ -20,38 +28,23 @@ A dictionary of particular features (e.g. custom fields) mapped to the NetBox mo
         ...
     },
     'webhooks': {
-        ...
+        'extras': ['configcontext', 'tag', ...],
+        'dcim': ['site', 'rack', 'devicetype', ...],
     },
     ...
 }
 ```
 
-### `plugin_menu_items`
+Supported model features are listed in the [features matrix](./models.md#features-matrix).
 
-Navigation menu items provided by NetBox plugins. Each plugin is registered as a key with the list of menu items it provides. An example:
+### `plugins`
 
-```python
-{
-    'Plugin A': (
-        <MenuItem>, <MenuItem>, <MenuItem>,
-    ),
-    'Plugin B': (
-        <MenuItem>, <MenuItem>, <MenuItem>,
-    ),
-}
-```
+This store maintains all registered items for plugins, such as navigation menus, template extensions, etc.
 
-### `plugin_template_extensions`
+### `search`
 
-Plugin content that gets embedded into core NetBox templates. The store comprises NetBox models registered as dictionary keys, each pointing to a list of applicable template extension classes that exist. An example:
+A dictionary mapping each model (identified by its app and label) to its search index class, if one has been registered for it.
 
-```python
-{
-    'dcim.site': [
-        <TemplateExtension>, <TemplateExtension>, <TemplateExtension>,
-    ],
-    'dcim.rack': [
-        <TemplateExtension>, <TemplateExtension>,
-    ],
-}
-```
+### `views`
+
+A hierarchical mapping of registered views for each model. Mappings are added using the `register_model_view()` decorator, and URLs paths can be generated from these using `get_model_urls()`.
diff --git a/docs/development/models.md b/docs/development/models.md
@@ -2,38 +2,43 @@
 
 ## Model Types
 
-A NetBox model represents a discrete object type such as a device or IP address. Per [Django convention](https://docs.djangoproject.com/en/stable/topics/db/models/), each model is defined as a Python class and has its own SQL table. All NetBox data models can be categorized by type.
+A NetBox model represents a discrete object type such as a device or IP address. Per [Django convention](https://docs.djangoproject.com/en/stable/topics/db/models/), each model is defined as a Python class and has its own table in the PostgreSQL database. All NetBox data models can be categorized by type.
 
-The Django [content types](https://docs.djangoproject.com/en/stable/ref/contrib/contenttypes/) framework can be used to reference models within the database. A ContentType instance references a model by its `app_label` and `name`: For example, the Site model is referred to as `dcim.site`. The content type combined with an object's primary key form a globally unique identifier for the object (e.g. `dcim.site:123`).
+The Django [content types](https://docs.djangoproject.com/en/stable/ref/contrib/contenttypes/) framework is used to map Django models to database tables. A ContentType instance references a model by its `app_label` and `name`: For example, the Site model within the DCIM app is referred to as `dcim.site`. The content type combined with an object's primary key form a globally unique identifier for the object (e.g. `dcim.site:123`).
 
 ### Features Matrix
 
-* [Change logging](../features/change-logging.md) - Changes to these objects are automatically recorded in the change log
-* [Webhooks](../integrations/webhooks.md) - NetBox is capable of generating outgoing webhooks for these objects
-* [Custom fields](../customization/custom-fields.md) - These models support the addition of user-defined fields
-* [Export templates](../customization/export-templates.md) - Users can create custom export templates for these models
-* [Tagging](../models/extras/tag.md) - The models can be tagged with user-defined tags
-* [Journaling](../features/journaling.md) - These models support persistent historical commentary
-* Nesting - These models can be nested recursively to create a hierarchy
-
-| Type               | Change Logging   | Webhooks         | Custom Fields    | Export Templates | Tags             | Journaling       | Nesting          |
-| ------------------ | ---------------- | ---------------- |------------------| ---------------- | ---------------- | ---------------- | ---------------- |
-| Primary            | :material-check: | :material-check: | :material-check: | :material-check: | :material-check: | :material-check: |                  |
-| Organizational     | :material-check: | :material-check: | :material-check: | :material-check: | :material-check: |                  |                  |
-| Nested Group       | :material-check: | :material-check: | :material-check: | :material-check: | :material-check: |                  | :material-check: |
-| Component          | :material-check: | :material-check: | :material-check: | :material-check: | :material-check: |                  |                  |
-| Component Template | :material-check: | :material-check: |                  |                  |                  |                  |                  |
+Depending on its classification, each NetBox model may support various features which enhance its operation. Each feature is enabled by inheriting from its designated mixin class, and some features also make use of the [application registry](./application-registry.md#model_features).
+
+| Feature                                                    | Feature Mixin           | Registry Key       | Description                                                                    |
+|------------------------------------------------------------|-------------------------|--------------------|--------------------------------------------------------------------------------|
+| [Change logging](../features/change-logging.md)            | `ChangeLoggingMixin`    | -                  | Changes to these objects are automatically recorded in the change log          |
+| Cloning                                                    | `CloningMixin`          | -                  | Provides the `clone()` method to prepare a copy                                |
+| [Custom fields](../customization/custom-fields.md)         | `CustomFieldsMixin`     | `custom_fields`    | These models support the addition of user-defined fields                       |
+| [Custom links](../customization/custom-links.md)           | `CustomLinksMixin`      | `custom_links`     | These models support the assignment of custom links                            |
+| [Custom validation](../customization/custom-validation.md) | `CustomValidationMixin` | -                  | Supports the enforcement of custom validation rules                            |
+| [Export templates](../customization/export-templates.md)   | `ExportTemplatesMixin`  | `export_templates` | Users can create custom export templates for these models                      |
+| [Job results](../features/background-jobs.md)              | `JobResultsMixin`       | `job_results`      | Users can create custom export templates for these models                      |
+| [Journaling](../features/journaling.md)                    | `JournalingMixin`       | `journaling`       | These models support persistent historical commentary                          |
+| [Synchronized data](../integrations/synchronized-data.md)  | `SyncedDataMixin`       | `synced_data`      | Certain model data can be automatically synchronized from a remote data source |
+| [Tagging](../models/extras/tag.md)                         | `TagsMixin`             | `tags`             | The models can be tagged with user-defined tags                                |
+| [Webhooks](../integrations/webhooks.md)                    | `WebhooksMixin`         | `webhooks`         | NetBox is capable of generating outgoing webhooks for these objects            |
 
 ## Models Index
 
 ### Primary Models
 
+These are considered the "core" application models which are used to model network infrastructure.
+
 * [circuits.Circuit](../models/circuits/circuit.md)
 * [circuits.Provider](../models/circuits/provider.md)
 * [circuits.ProviderNetwork](../models/circuits/providernetwork.md)
+* [core.DataSource](../models/core/datasource.md)
 * [dcim.Cable](../models/dcim/cable.md)
 * [dcim.Device](../models/dcim/device.md)
 * [dcim.DeviceType](../models/dcim/devicetype.md)
+* [dcim.Module](../models/dcim/module.md)
+* [dcim.ModuleType](../models/dcim/moduletype.md)
 * [dcim.PowerFeed](../models/dcim/powerfeed.md)
 * [dcim.PowerPanel](../models/dcim/powerpanel.md)
 * [dcim.Rack](../models/dcim/rack.md)
@@ -47,10 +52,10 @@ The Django [content types](https://docs.djangoproject.com/en/stable/ref/contrib/
 * [ipam.IPAddress](../models/ipam/ipaddress.md)
 * [ipam.IPRange](../models/ipam/iprange.md)
 * [ipam.L2VPN](../models/ipam/l2vpn.md)
-* [ipam.L2VPNTermination](../models/ipam/l2vpntermination.md)
 * [ipam.Prefix](../models/ipam/prefix.md)
 * [ipam.RouteTarget](../models/ipam/routetarget.md)
 * [ipam.Service](../models/ipam/service.md)
+* [ipam.ServiceTemplate](../models/ipam/servicetemplate.md)
 * [ipam.VLAN](../models/ipam/vlan.md)
 * [ipam.VRF](../models/ipam/vrf.md)
 * [tenancy.Contact](../models/tenancy/contact.md)
@@ -62,6 +67,8 @@ The Django [content types](https://docs.djangoproject.com/en/stable/ref/contrib/
 
 ### Organizational Models
 
+Organization models are used to organize and classify primary models.
+
 * [circuits.CircuitType](../models/circuits/circuittype.md)
 * [dcim.DeviceRole](../models/dcim/devicerole.md)
 * [dcim.Manufacturer](../models/dcim/manufacturer.md)
@@ -76,6 +83,8 @@ The Django [content types](https://docs.djangoproject.com/en/stable/ref/contrib/
 
 ### Nested Group Models
 
+Nested group models behave like organizational model, but self-nest within a recursive hierarchy. For example, the Region model can be used to represent a hierarchy of countries, states, and cities.
+
 * [dcim.Location](../models/dcim/location.md) (formerly RackGroup)
 * [dcim.Region](../models/dcim/region.md)
 * [dcim.SiteGroup](../models/dcim/sitegroup.md)
@@ -85,24 +94,31 @@ The Django [content types](https://docs.djangoproject.com/en/stable/ref/contrib/
 
 ### Component Models
 
+Component models represent individual physical or virtual components belonging to a device or virtual machine.
+
 * [dcim.ConsolePort](../models/dcim/consoleport.md)
 * [dcim.ConsoleServerPort](../models/dcim/consoleserverport.md)
 * [dcim.DeviceBay](../models/dcim/devicebay.md)
 * [dcim.FrontPort](../models/dcim/frontport.md)
 * [dcim.Interface](../models/dcim/interface.md)
 * [dcim.InventoryItem](../models/dcim/inventoryitem.md)
+* [dcim.ModuleBay](../models/dcim/modulebay.md)
 * [dcim.PowerOutlet](../models/dcim/poweroutlet.md)
 * [dcim.PowerPort](../models/dcim/powerport.md)
 * [dcim.RearPort](../models/dcim/rearport.md)
 * [virtualization.VMInterface](../models/virtualization/vminterface.md)
 
 ### Component Template Models
 
+These function as templates to effect the replication of device and virtual machine components. Component template models support a limited feature set, including change logging, custom validation, and webhooks.
+
 * [dcim.ConsolePortTemplate](../models/dcim/consoleporttemplate.md)
 * [dcim.ConsoleServerPortTemplate](../models/dcim/consoleserverporttemplate.md)
 * [dcim.DeviceBayTemplate](../models/dcim/devicebaytemplate.md)
 * [dcim.FrontPortTemplate](../models/dcim/frontporttemplate.md)
 * [dcim.InterfaceTemplate](../models/dcim/interfacetemplate.md)
+* [dcim.InventoryItemTemplate](../models/dcim/inventoryitemtemplate.md)
+* [dcim.ModuleBayTemplate](../models/dcim/modulebaytemplate.md)
 * [dcim.PowerOutletTemplate](../models/dcim/poweroutlettemplate.md)
 * [dcim.PowerPortTemplate](../models/dcim/powerporttemplate.md)
 * [dcim.RearPortTemplate](../models/dcim/rearporttemplate.md)
diff --git a/docs/features/background-jobs.md b/docs/features/background-jobs.md
@@ -0,0 +1,13 @@
+# Background Jobs
+
+NetBox includes the ability to execute certain functions as background tasks. These include:
+
+* [Report](../customization/reports.md) execution
+* [Custom script](../customization/custom-scripts.md) execution
+* Synchronization of [remote data sources](../integrations/synchronized-data.md)
+
+Additionally, NetBox plugins can enqueue their own background tasks. This is accomplished using the [JobResult model](../models/extras/jobresult.md). Background tasks are executed by the `rqworker` process(es).
+
+## Scheduled Jobs
+
+Background jobs can be configured to run immediately, or at a set time in the future. Scheduled jobs can also be configured to repeat at a set interval.
diff --git a/docs/integrations/synchronized-data.md b/docs/integrations/synchronized-data.md
@@ -0,0 +1,9 @@
+# Synchronized Data
+
+Some NetBox models support automatic synchronization of certain attributes from remote [data sources](../models/core/datasource.md), such as a git repository hosted on GitHub or GitLab. Data from the authoritative remote source is synchronized locally in NetBox as [data files](../models/core/datafile.md).
+
+The following features support the use of synchronized data:
+
+* [Configuration templates](../features/configuration-rendering.md)
+* [Configuration context data](../features/context-data.md)
+* [Export templates](../customization/export-templates.md)
diff --git a/docs/models/extras/jobresult.md b/docs/models/extras/jobresult.md
@@ -0,0 +1,54 @@
+# Job Results
+
+The JobResult model is used to schedule and record the execution of [background tasks](../../features/background-jobs.md).
+
+## Fields
+
+### Name
+
+The name or other identifier of the NetBox object with which the job is associated.
+
+## Object Type
+
+The type of object (model) associated with this job.
+
+### Created
+
+The date and time at which the job itself was created.
+
+### Scheduled
+
+The date and time at which the job is/was scheduled to execute (if not submitted for immediate execution at the time of creation).
+
+### Interval
+
+The interval (in minutes) at which a scheduled job should re-execute.
+
+### Completed
+
+The date and time at which the job completed (if complete).
+
+### User
+
+The user who created the job.
+
+### Status
+
+The job's current status. Potential values include:
+
+| Value | Description |
+|-------|-------------|
+| Pending | Awaiting execution by an RQ worker process |
+| Scheduled | Scheduled for a future date/time |
+| Running | Currently executing |
+| Completed | Successfully completed |
+| Failed | The job did not complete successfully |
+| Errored | An unexpected error was encountered during execution |
+
+### Data
+
+Any data associated with the execution of the job, such as log output.
+
+### Job ID
+
+The job's UUID, used for unique identification within a queue.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -77,6 +77,7 @@ nav:
         - Configuration Rendering: 'features/configuration-rendering.md'
         - Change Logging: 'features/change-logging.md'
         - Journaling: 'features/journaling.md'
+        - Background Jobs: 'features/background-jobs.md'
         - Auth & Permissions: 'features/authentication-permissions.md'
         - API & Integration: 'features/api-integration.md'
         - Customization: 'features/customization.md'
@@ -117,6 +118,7 @@ nav:
         - REST API: 'integrations/rest-api.md'
         - GraphQL API: 'integrations/graphql-api.md'
         - Webhooks: 'integrations/webhooks.md'
+        - Synchronized Data: 'integrations/synchronized-data.md'
         - NAPALM: 'integrations/napalm.md'
         - Prometheus Metrics: 'integrations/prometheus-metrics.md'
     - Plugins:
@@ -153,6 +155,9 @@ nav:
             - Circuit Type: 'models/circuits/circuittype.md'
             - Provider: 'models/circuits/provider.md'
             - Provider Network: 'models/circuits/providernetwork.md'
+        - Core:
+            - DataFile: 'models/core/datafile.md'
+            - DataSource: 'models/core/datasource.md'
         - DCIM:
             - Cable: 'models/dcim/cable.md'
             - ConsolePort: 'models/dcim/consoleport.md'
@@ -202,6 +207,7 @@ nav:
             - CustomLink: 'models/extras/customlink.md'
             - ExportTemplate: 'models/extras/exporttemplate.md'
             - ImageAttachment: 'models/extras/imageattachment.md'
+            - JobResult: 'models/extras/jobresult.md'
             - JournalEntry: 'models/extras/journalentry.md'
             - SavedFilter: 'models/extras/savedfilter.md'
             - StagedChange: 'models/extras/stagedchange.md'