Continued work on feature docs

docs/development/models.md

@@ -9,7 +9,7 @@ The Django [content types](https://docs.djangoproject.com/en/stable/ref/contrib/
 ### Features Matrix
 
 * [Change logging](../features/change-logging.md) - Changes to these objects are automatically recorded in the change log
-* [Webhooks](../features/webhooks.md) - NetBox is capable of generating outgoing webhooks for these objects
+* [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](../features/tags.md) - The models can be tagged with user-defined tags

docs/features/context-data.md

@@ -1,69 +1,34 @@
-# Configuration Contexts
+# Context Data
 
-Sometimes it is desirable to associate additional data with a group of devices or virtual machines to aid in automated configuration. For example, you might want to associate a set of syslog servers for all devices within a particular region. Context data enables the association of extra user-defined data with devices and virtual machines grouped by one or more of the following assignments:
+Configuration context data (or "config contexts" for short) is a powerful feature that enables users to define arbitrary data that applies to device and virtual machines based on certain characteristics. For example, suppose you want to define syslog servers for devices assigned to sites within a particular region. In NetBox, you can create a config context instance containing this data and apply it to the desired region. All devices within this region will now include this data when fetched via an API.
-
-* Region
-* Site group
-* Site
-* Location (devices only)
-* Device type (devices only)
-* Role
-* Platform
-* Cluster type (VMs only)
-* Cluster group (VMs only)
-* Cluster (VMs only)
-* Tenant group
-* Tenant
-* Tag
-
-## Hierarchical Rendering
-
-Context data is arranged hierarchically, so that data with a higher weight can be entered to override lower-weight data. Multiple instances of data are automatically merged by NetBox to present a single dictionary for each object.
-
-For example, suppose we want to specify a set of syslog and NTP servers for all devices within a region. We could create a config context instance with a weight of 1000 assigned to the region, with the following JSON data:
-
-```json
-{
-    "ntp-servers": [
-        "172.16.10.22",
-        "172.16.10.33"
-    ],
-    "syslog-servers": [
-        "172.16.9.100",
-        "172.16.9.101"
-    ]
-}
-```
-
-But suppose there's a problem at one particular site within this region preventing traffic from reaching the regional syslog server. Devices there need to use a local syslog server instead of the two defined above. We'll create a second config context assigned only to that site with a weight of 2000 and the following data:
 
 ```json
 {
     "syslog-servers": [
-        "192.168.43.107"
+        "192.168.43.107",
+        "192.168.48.112"
     ]
 }
 ```
 
-When the context data for a device at this site is rendered, the second, higher-weight data overwrite the first, resulting in the following:
+While this is handy on its own, the real power of context data stems from its ability to be merged and overridden using multiple instances. For example, perhaps you need to define _different_ syslog servers within the region for a particular device role. You can create a second config context with the appropriate data and a higher weight, and apply it to the desired role. This will override the lower-weight data that applies to the entire region. As you can imagine, this flexibility can cater to many complex use cases.
 
-```json
+There are no restrictions around what data can be stored in a configuration context, so long as it can be expressed in JSON. Additionally, each device and VM may have local context data defined: This data is stored directly on the assigned object, and applies to it only. This is a convenient way for "attaching" miscellaneous data to a single device or VM as needed.
-{
-    "ntp-servers": [
-        "172.16.10.22",
-        "172.16.10.33"
-    ],
-    "syslog-servers": [
-        "192.168.43.107"
-    ]
-}
-```
 
-Data from the higher-weight context overwrites conflicting data from the lower-weight context, while the non-conflicting portion of the lower-weight context (the list of NTP servers) is preserved.
+Config contexts can be computed for objects based on the following criteria:
 
-## Local Context Data
+| Type          | Devices          | Virtual Machines |
-
+|---------------|------------------|------------------|
-Devices and virtual machines may also have a local config context defined. This local context will _always_ take precedence over any separate config context objects which apply to the device/VM. This is useful in situations where we need to call out a specific deviation in the data for a particular object.
+| Region        | :material-check: | :material-check: |
-
+| Site group    | :material-check: | :material-check: |
-!!! warning
+| Site          | :material-check: | :material-check: |
-    If you find that you're routinely defining local context data for many individual devices or virtual machines, custom fields may offer a more effective solution.
+| Location      | :material-check: |                  |
+| Device type   | :material-check: |                  |
+| Role          | :material-check: | :material-check: |
+| Platform      | :material-check: | :material-check: |
+| Cluster type  |                  | :material-check: |
+| Cluster group |                  | :material-check: |
+| Cluster       |                  | :material-check: |
+| Tenant group  | :material-check: | :material-check: |
+| Tenant        | :material-check: | :material-check: |
+| Tag           | :material-check: | :material-check: |

docs/features/customization.md

@@ -1,3 +1,41 @@
 # Customization
 
+While NetBox strives to meet the needs of every network, the needs of users to cater to their own unique environments cannot be ignored. NetBox was built with this in mind, and can be customized in many ways to better suit your particular needs.
+
+## Custom Fields
+
+While NetBox provides a rather extensive data model out of the box, the need may arise to store certain additional data associated with NetBox objects. For example, you might need to record the invoice ID alongside an installed device, or record an approving authority when creating a new IP prefix. NetBox administrators can create custom fields on built-in objects to meet these needs.
+
+NetBox supports many types of custom field, from basic data types like strings and integers, to complex structures like selection lists or raw JSON. It's even possible to add a custom field which references other NetBox objects. Custom field data is stored directly alongside the object to which it is applied in the database, which ensures minimal performance impact. And custom field data can be written and read via the REST API, just like built-in fields.
+
+To learn more about this feature, check out the [custom field documentation](../customization/custom-fields.md).
+
+## Custom Links
+
 TODO
+
+To learn more about this feature, check out the [custom link documentation](../customization/custom-links.md).
+
+## Custom Validation
+
+TODO
+
+To learn more about this feature, check out the [custom validation documentation](../customization/custom-validation.md).
+
+## Export Templates
+
+TODO
+
+To learn more about this feature, check out the [export template documentation](../customization/export-templates.md).
+
+## Reports
+
+TODO
+
+To learn more about this feature, check out the [documentation for reports](../customization/reports.md).
+
+## Custom Scripts
+
+TODO
+
+To learn more about this feature, check out the [documentation for custom scripts](../customization/custom-scripts.md).

docs/features/integrations.md

@@ -0,0 +1,41 @@
+# Integrations
+
+NetBox includes a slew of features which enable integration with other tools and resources powering your network.
+
+## REST API
+
+NetBox's REST API, powered by the [Django REST Framework](https://www.django-rest-framework.org/), provides a robust yet accessible interface for creating, modifying, and deleting objects. Employing HTTP for transfer and JSON for data encapsulation, the REST API is easily consumed by clients on any platform and extremely well suited for automation tasks.
+
+```no-highlight
+curl -s -X POST \
+-H "Authorization: Token $TOKEN" \
+-H "Content-Type: application/json" \
+http://netbox/api/ipam/prefixes/ \
+--data '{"prefix": "192.0.2.0/24", "site": {"name": "Branch 12"}}'
+```
+
+The REST API employs token-based authentication, which maps API clients to user accounts and their assigned permissions. The API endpoints are fully documented using OpenAPI, and NetBox even includes a convenient browser-based version of the API for exploration. The open source [pynetbox](https://github.com/netbox-community/pynetbox) and [go-netbox](https://github.com/netbox-community/go-netbox) API client libraries are also available for Python and Go, respectively.
+
+To learn more about this feature, check out the [REST API documentation](../integrations/rest-api.md).
+
+## GraphQL API
+
+NetBox also provides a [GraphQL](https://graphql.org/) API to complement its REST API. GraphQL enables complex queries for arbitrary objects and fields, enabling the client to retrieve only the specific data it needs from NetBox. This is a special-purpose read-only API intended for efficient queries. Like the REST API, the GraphQL API employs token-based authentication.
+
+To learn more about this feature, check out the [GraphQL API documentation](../integrations/graphql-api.md).
+
+## Webhooks
+
+A webhook is a mechanism for conveying to some external system a change that took place in NetBox. For example, you may want to notify a monitoring system whenever the status of a device is updated in NetBox. This can be done by creating a webhook for the device model in NetBox and identifying the webhook receiver. When NetBox detects a change to a device, an HTTP request containing the details of the change and who made it be sent to the specified receiver. Webhooks are an excellent mechanism for building event-based automation processes.
+
+To learn more about this feature, check out the [webhooks documentation](../integrations/webhooks.md).
+
+## NAPALM
+
+[NAPALM](https://github.com/napalm-automation/napalm) is a Python library which enables direct interaction with network devices of various platforms. When configured, NetBox supports fetching live operational and status data directly from network devices to be compared to what has been defined in NetBox. This allows for easily validating the device's operational state against its desired state. Additionally, NetBox's REST API can act as a sort of proxy for NAPALM commands, allowing external clients to interact with network devices by sending HTTP requests to the appropriate API endpoint.
+
+To learn more about this feature, check out the [NAPALM documentation](../integrations/napalm.md).
+
+## Prometheus Metrics
+
+NetBox includes a special `/metrics` view which exposes metrics for a [Prometheus](https://prometheus.io/) scraper, powered by the open source [django-prometheus](https://github.com/korfuri/django-prometheus) library. To learn more about this feature, check out the [Prometheus metrics documentation](../integrations/prometheus-metrics.md).

docs/features/tags.md

@@ -1,17 +0,0 @@
-# Tags
-
-Tags are user-defined labels which can be applied to a variety of objects within NetBox. They can be used to establish dimensions of organization beyond the relationships built into NetBox. For example, you might create a tag to identify a particular ownership or condition across several types of objects.
-
-Each tag has a label, color, and a URL-friendly slug. For example, the slug for a tag named "Dunder Mifflin, Inc." would be `dunder-mifflin-inc`. The slug is generated automatically and makes tags easier to work with as URL parameters. Each tag can also be assigned a description indicating its purpose.
-
-Objects can be filtered by the tags they have applied. For example, the following API request will retrieve all devices tagged as "monitored":
-
-```no-highlight
-GET /api/dcim/devices/?tag=monitored
-```
-
-The `tag` filter can be specified multiple times to match only objects which have _all_ of the specified tags assigned:
-
-```no-highlight
-GET /api/dcim/devices/?tag=monitored&tag=deprecated
-```

docs/models/extras/configcontext.md

@@ -0,0 +1,69 @@
+# Configuration Contexts
+
+Sometimes it is desirable to associate additional data with a group of devices or virtual machines to aid in automated configuration. For example, you might want to associate a set of syslog servers for all devices within a particular region. Context data enables the association of extra user-defined data with devices and virtual machines grouped by one or more of the following assignments:
+
+* Region
+* Site group
+* Site
+* Location (devices only)
+* Device type (devices only)
+* Role
+* Platform
+* Cluster type (VMs only)
+* Cluster group (VMs only)
+* Cluster (VMs only)
+* Tenant group
+* Tenant
+* Tag
+
+## Hierarchical Rendering
+
+Context data is arranged hierarchically, so that data with a higher weight can be entered to override lower-weight data. Multiple instances of data are automatically merged by NetBox to present a single dictionary for each object.
+
+For example, suppose we want to specify a set of syslog and NTP servers for all devices within a region. We could create a config context instance with a weight of 1000 assigned to the region, with the following JSON data:
+
+```json
+{
+    "ntp-servers": [
+        "172.16.10.22",
+        "172.16.10.33"
+    ],
+    "syslog-servers": [
+        "172.16.9.100",
+        "172.16.9.101"
+    ]
+}
+```
+
+But suppose there's a problem at one particular site within this region preventing traffic from reaching the regional syslog server. Devices there need to use a local syslog server instead of the two defined above. We'll create a second config context assigned only to that site with a weight of 2000 and the following data:
+
+```json
+{
+    "syslog-servers": [
+        "192.168.43.107"
+    ]
+}
+```
+
+When the context data for a device at this site is rendered, the second, higher-weight data overwrite the first, resulting in the following:
+
+```json
+{
+    "ntp-servers": [
+        "172.16.10.22",
+        "172.16.10.33"
+    ],
+    "syslog-servers": [
+        "192.168.43.107"
+    ]
+}
+```
+
+Data from the higher-weight context overwrites conflicting data from the lower-weight context, while the non-conflicting portion of the lower-weight context (the list of NTP servers) is preserved.
+
+## Local Context Data
+
+Devices and virtual machines may also have a local config context defined. This local context will _always_ take precedence over any separate config context objects which apply to the device/VM. This is useful in situations where we need to call out a specific deviation in the data for a particular object.
+
+!!! warning
+    If you find that you're routinely defining local context data for many individual devices or virtual machines, custom fields may offer a more effective solution.

docs/models/extras/tag.md

@@ -0,0 +1,17 @@
+# Tags
+
+Tags are user-defined labels which can be applied to a variety of objects within NetBox. They can be used to establish dimensions of organization beyond the relationships built into NetBox. For example, you might create a tag to identify a particular ownership or condition across several types of objects.
+
+Each tag has a label, color, and a URL-friendly slug. For example, the slug for a tag named "Dunder Mifflin, Inc." would be `dunder-mifflin-inc`. The slug is generated automatically and makes tags easier to work with as URL parameters. Each tag can also be assigned a description indicating its purpose.
+
+Objects can be filtered by the tags they have applied. For example, the following API request will retrieve all devices tagged as "monitored":
+
+```no-highlight
+GET /api/dcim/devices/?tag=monitored
+```
+
+The `tag` filter can be specified multiple times to match only objects which have _all_ of the specified tags assigned:
+
+```no-highlight
+GET /api/dcim/devices/?tag=monitored&tag=deprecated
+```

mkdocs.yml

@@ -73,8 +73,8 @@ nav:
         - Context Data: 'features/context-data.md'
         - Change Logging: 'features/change-logging.md'
         - Journaling: 'features/journaling.md'
-        - Webhooks: 'features/webhooks.md'
         - Tags: 'features/tags.md'
+        - Integrations: 'features/integrations.md'
         - Customization: 'features/customization.md'
         - Object-Based Permissions: 'features/permissions.md'
         - Single Sign-On (SSO): 'features/sso.md'
@@ -114,6 +114,7 @@ nav:
     - Integrations:
         - REST API: 'integrations/rest-api.md'
         - GraphQL API: 'integrations/graphql-api.md'
+        - Webhooks: 'integrations/webhooks.md'
         - NAPALM: 'integrations/napalm.md'
         - Prometheus Metrics: 'integrations/prometheus-metrics.md'
     - Plugins:
@@ -188,6 +189,9 @@ nav:
             - Site: 'models/dcim/site.md'
             - SiteGroup: 'models/dcim/sitegroup.md'
             - VirtualChassis: 'models/dcim/virtualchassis.md'
+        - Extras:
+            - ConfigContext: 'models/extras/configcontext.md'
+            - Tag: 'models/extras/tag.md'
         - IPAM:
             - ASN: 'models/ipam/asn.md'
             - Aggregate: 'models/ipam/aggregate.md'