Refreshed tenancy model documentation

docs/features/contacts.md

@@ -26,3 +26,20 @@ A contact role defines the relationship of a contact to an assigned object. For
 A contact should represent an individual or permanent point of contact. Each contact must define a name, and may optionally include a title, phone number, email address, and related details.
 
 Contacts are reused for assignments, so each unique contact must be created only once and can be assigned to any number of NetBox objects, and there is no limit to the number of assigned contacts an object may have. Most core objects in NetBox can have contacts assigned to them.
+
+The following models support the assignment of contacts:
+
+* circuits.Circuit
+* circuits.Provider
+* dcim.Device
+* dcim.Location
+* dcim.Manufacturer
+* dcim.PowerPanel
+* dcim.Rack
+* dcim.Region
+* dcim.Site
+* dcim.SiteGroup
+* tenancy.Tenant
+* virtualization.Cluster
+* virtualization.ClusterGroup
+* virtualization.VirtualMachine

docs/features/tenancy.md

@@ -13,10 +13,26 @@ click TenantGroup "../../models/tenancy/tenantgroup/"
 
 ## Tenant Groups
 
-Tenants can be grouped by any logic that your use case demands, and groups can nested recursively for maximum flexibility. For example, You might define a parent "Customers" group with child groups "Current" and "Past" within it. A tenant can be assigned to a group at any level within the hierarchy.
+Tenants can be grouped by any logic that your use case demands, and groups can be nested recursively for maximum flexibility. For example, You might define a parent "Customers" group with child groups "Current" and "Past" within it. A tenant can be assigned to a group at any level within the hierarchy.
 
 ## Tenants
 
 Typically, the tenant model is used to represent a customer or internal organization, however it can be used for whatever purpose meets your needs.
 
 Most core objects within NetBox can be assigned to particular tenant, so this model provides a very convenient way to correlate ownership across object types. For example, each of your customers might have its own racks, devices, IP addresses, circuits and so on: These can all be easily tracked via tenant assignment.
+
+The following objects can be assigned to tenants:
+
+* Sites
+* Racks
+* Rack reservations
+* Devices
+* VRFs
+* Prefixes
+* IP addresses
+* VLANs
+* Circuits
+* Clusters
+* Virtual machines
+
+Tenant assignment is used to signify the ownership of an object in NetBox. As such, each object may only be owned by a single tenant. For example, if you have a firewall dedicated to a particular customer, you would assign it to the tenant which represents that customer. However, if the firewall serves multiple customers, it doesn't *belong* to any particular customer, so tenant assignment would not be appropriate.

docs/models/tenancy/contact.md

@@ -1,31 +1,33 @@
 # Contacts
 
-A contact represent an individual or group that has been associated with an object in NetBox for administrative reasons. For example, you might assign one or more operational contacts to each site. Contacts can be arranged within nested contact groups.
-
-Each contact must include a name, which is unique to its parent group (if any). The following optional descriptors are also available:
-
-* Title
-* Phone
-* Email
-* Address
-
-## Contact Assignment
-
-Each contact can be assigned to one or more objects, allowing for the efficient reuse of contact information. When assigning a contact to an object, the user may optionally specify a role and/or priority (primary, secondary, tertiary, or inactive) to better convey the nature of the contact's relationship to the assigned object.
-
-The following models support the assignment of contacts:
-
-* circuits.Circuit
-* circuits.Provider
-* dcim.Device
-* dcim.Location
-* dcim.Manufacturer
-* dcim.PowerPanel
-* dcim.Rack
-* dcim.Region
-* dcim.Site
-* dcim.SiteGroup
-* tenancy.Tenant
-* virtualization.Cluster
-* virtualization.ClusterGroup
-* virtualization.VirtualMachine
+A contact represents an individual or group that has been associated with an object in NetBox for administrative reasons. For example, you might assign one or more operational contacts to each site.
+
+## Fields
+
+### Group
+
+The [contact group](./contactgroup.md) to which this contact is assigned (if any).
+
+### Name
+
+The name of the contact. This may be an individual or a team/department. (This is the only required contact detail; all others are optional.)
+
+### Title
+
+The contact's title or role.
+
+### Phone
+
+The contact's phone number. (Note that NetBox does _not_ enforce a particular numbering format.)
+
+### Email
+
+The contact's email address.
+
+### Address
+
+The contact's physical or mailing address.
+
+### Link
+
+A URL to reach the contact via some other means.

docs/models/tenancy/contactgroup.md

@@ -1,3 +1,17 @@
 # Contact Groups
 
-Contacts can be organized into arbitrary groups. These groups can be recursively nested for convenience. Each contact within a group must have a unique name, but other attributes can be repeated.
+[Contacts](./contact.md) can be organized into arbitrary groups. These groups can be recursively nested for convenience. Each contact within a group must have a unique name, but other attributes can be repeated.
+
+## Fields
+
+### Parent
+
+The parent contact group (if any).
+
+### Name
+
+A unique human-friendly name.
+
+### Slug
+
+A unique URL-friendly identifier. (This value can be used for filtering.)

docs/models/tenancy/contactrole.md

@@ -1,3 +1,13 @@
 # Contact Roles
 
-Contacts can be organized by functional roles, which are fully customizable by the user. For example, you might create roles for administrative, operational, or emergency contacts.
+[Contacts](./contact.md) can be organized by functional roles, which are fully customizable by the user. For example, you might create roles for administrative, operational, or emergency contacts.
+
+## Fields
+
+### Name
+
+A unique human-friendly name.
+
+### Slug
+
+A unique URL-friendly identifier. (This value can be used for filtering.)

docs/models/tenancy/tenant.md

@@ -1,17 +1,17 @@
 # Tenants
 
-A tenant represents a discrete grouping of resources used for administrative purposes. Typically, tenants are used to represent individual customers or internal departments within an organization. The following objects can be assigned to tenants:
-
-* Sites
-* Racks
-* Rack reservations
-* Devices
-* VRFs
-* Prefixes
-* IP addresses
-* VLANs
-* Circuits
-* Clusters
-* Virtual machines
-
-Tenant assignment is used to signify the ownership of an object in NetBox. As such, each object may only be owned by a single tenant. For example, if you have a firewall dedicated to a particular customer, you would assign it to the tenant which represents that customer. However, if the firewall serves multiple customers, it doesn't *belong* to any particular customer, so tenant assignment would not be appropriate.
+A tenant represents a discrete grouping of resources used for administrative purposes. Typically, tenants are used to represent individual customers or internal departments within an organization. 
+
+## Fields
+
+### Name
+
+A unique human-friendly name.
+
+### Slug
+
+A unique URL-friendly identifier. (This value can be used for filtering.)
+
+### Group
+
+The [tenant group](./tenantgroup.md) to which this tenant belongs (if any).

docs/models/tenancy/tenantgroup.md

@@ -1,5 +1,19 @@
 # Tenant Groups
 
-Tenants can be organized by custom groups. For instance, you might create one group called "Customers" and one called "Departments." The assignment of a tenant to a group is optional.
+[Tenants](./tenant.md) can be organized by custom groups. For instance, you might create one group called "Customers" and one called "Departments." The assignment of a tenant to a group is optional.
 
 Tenant groups may be nested recursively to achieve a multi-level hierarchy. For example, you might have a group called "Customers" containing subgroups of individual tenants grouped by product or account team.
+
+## Fields
+
+### Parent
+
+The parent tenant group (if any).
+
+### Name
+
+A unique human-friendly name.
+
+### Slug
+
+A unique URL-friendly identifier. (This value can be used for filtering.)