Refreshed circuits model documentation

docs/models/circuits/circuit.md

@@ -1,19 +1,49 @@
 # Circuits
 
-A communications circuit represents a single _physical_ link connecting exactly two endpoints, commonly referred to as its A and Z terminations. A circuit in NetBox may have zero, one, or two terminations defined. It is common to have only one termination defined when you don't necessarily care about the details of the provider side of the circuit, e.g. for Internet access circuits. Both terminations would likely be modeled for circuits which connect one customer site to another.
+A circuit represents a physical point-to-point data connection, typically used to interconnect sites across considerable distances (e.g. to deliver Internet connectivity).
 
-Each circuit is associated with a provider and a user-defined type. For example, you might have Internet access circuits delivered to each site by one provider, and private MPLS circuits delivered by another. Each circuit must be assigned a circuit ID, each of which must be unique per provider.
+## Fields
 
-Each circuit is also assigned one of the following operational statuses:
+### Provider
 
-* Planned
-* Provisioning
-* Active
-* Offline
-* Deprovisioning
-* Decommissioned
+The [provider](./provider.md) to which this circuit belongs.
 
-Circuits also have optional fields for annotating their installation and termination dates and commit rate, and may be assigned to NetBox tenants.
+### Circuit ID
 
-!!! note
-    NetBox currently models only physical circuits: those which have exactly two endpoints. It is common to layer virtualized constructs (_virtual circuits_) such as MPLS or EVPN tunnels on top of these, however NetBox does not yet support virtual circuit modeling.
+An identifier for this circuit. This must be unique to the assigned provider. (Circuits assigned to different providers may have the same circuit ID.)
+
+### Circuit Type
+
+Each circuit is classified by a user-defined [circuit type](./circuittype.md). Generally this is something like "Internet access," "MPLS/VPN," etc.
+
+### Status
+
+The operational status of the circuit. By default, the following statuses are available:
+
+| Name           |
+|----------------|
+| Planned        |
+| Provisioning   |
+| Active         |
+| Offline        |
+| Deprovisioning |
+| Decommissioned |
+
+!!! tip "Custom circuit statuses"
+    Additional circuit statuses may be defined by setting `Circuit.status` under the [`FIELD_CHOICES`](../../configuration/data-validation.md#field_choices) configuration parameter.
+
+### Description
+
+A brief description of the circuit.
+
+### Installation Date
+
+The date on which the circuit was installed.
+
+### Termination Date
+
+The date on which the circuit is scheduled to be disconnected.
+
+### Commit Rate
+
+The committed rate (throughput) of the circuit, in kilobits per second.

docs/models/circuits/circuittermination.md

@@ -1,10 +1,46 @@
 # Circuit Terminations
 
-The association of a circuit with a particular site and/or device is modeled separately as a circuit termination. A circuit may have up to two terminations, labeled A and Z. A single-termination circuit can be used when you don't know (or care) about the far end of a circuit (for example, an Internet access circuit which connects to a transit provider). A dual-termination circuit is useful for tracking circuits which connect two sites.
-
-Each circuit termination is attached to either a site or to a provider network. Site terminations may optionally be connected via a cable to a specific device interface or port within that site. Each termination must be assigned a port speed, and can optionally be assigned an upstream speed if it differs from the downstream speed (a common scenario with e.g. DOCSIS cable modems). Fields are also available to track cross-connect and patch panel details.
+Each circuit may have up to two terminations, designated A and Z. At either termination, a circuit may connect to a site, device interface (via a cable), or to a provider network.
 
 In adherence with NetBox's philosophy of closely modeling the real world, a circuit may be connected only to a physical interface. For example, circuits may not terminate to LAG interfaces, which are virtual in nature. In such cases, a separate physical circuit is associated with each LAG member interface and each needs to be modeled discretely.
 
 !!! note
     A circuit in NetBox represents a physical link, and cannot have more than two endpoints. When modeling a multi-point topology, each leg of the topology must be defined as a discrete circuit, with one end terminating within the provider's infrastructure. The provider network model is ideal for representing these networks.
+
+## Fields
+
+### Circuit
+
+The [circuit](./circuit.md) to which this termination belongs.
+
+### Termination Side
+
+Designates the termination as forming either the A or Z end of the circuit.
+
+### Mark Connected
+
+If selected, the circuit termination will be considered "connected" even if no cable has been connected to it in NetBox.
+
+### Site
+
+The [site](../dcim/site.md) with which this circuit termination is associated. Once created, a cable can be connected between the circuit termination and a device interface (or similar component).
+
+### Provider Network
+
+Circuits which do not connect to a site modeled by NetBox can instead be terminated to a [provider network](./providernetwork.md) representing an unknown network operated by a [provider](./provider.md).
+
+### Port Speed
+
+The operating speed of the terminated interface, in kilobits per second. This is useful for documenting the speed of a circuit when the actual interface to which it terminates is not being modeled in NetBox.
+
+### Upstream Speed
+
+The upstream speed of the terminated interface (in kilobits per second), if different from the downstream speed (a common scenario with e.g. DOCSIS cable modems).
+
+### Cross-connect ID
+
+In a data center environment, circuits are often delivered via a local cross-connect. While it may not be appropriate to model the cross-connect itself in NetBox, it's a good idea to record its ID for reference where applicable.
+
+### Patch Panel & Port(s)
+
+Similar to the cross-connect ID, this field can be used to track physical connection details which may be outside the scope of what is being modeled in NetBox.

docs/models/circuits/circuittype.md

@@ -1,8 +1,18 @@
 # Circuit Types
 
-Circuits are classified by functional type. These types are completely customizable, and are typically used to convey the type of service being delivered over a circuit. For example, you might define circuit types for:
+[Circuits](./circuit.md) are classified by functional type. These types are completely customizable, and are typically used to convey the type of service being delivered over a circuit. For example, you might define circuit types for:
 
 * Internet transit
 * Out-of-band connectivity
 * Peering
 * Private backhaul
+
+## Fields
+
+### Name
+
+A unique human-friendly name.
+
+### Slug
+
+A unique URL-friendly identifier. (This value can be used for filtering.)

docs/models/circuits/provider.md

@@ -1,5 +1,40 @@
 # Providers
 
-A circuit provider is any entity which provides some form of connectivity of among sites or organizations within a site. While this obviously includes carriers which offer Internet and private transit service, it might also include Internet exchange (IX) points and even organizations with whom you peer directly. Each circuit within NetBox must be assigned a provider and a circuit ID which is unique to that provider.
+A provider is any entity which provides some form of connectivity of among sites or organizations within a site. While this obviously includes carriers which offer Internet and private transit service, it might also include Internet exchange (IX) points and even organizations with whom you peer directly. Each [circuit](./circuit.md) within NetBox must be assigned a provider and a circuit ID which is unique to that provider.
 
-Each provider may be assigned an autonomous system number (ASN), an account number, and contact information.
+## Fields
+
+### Name
+
+A unique human-friendly name.
+
+### Slug
+
+A unique URL-friendly identifier. (This value can be used for filtering.)
+
+### ASN
+
+The AS number assigned to this provider.
+
+!!! warning "Legacy field"
+    This field is being removed in NetBox v3.4. Users are highly encouraged to use the [ASN model](../ipam/asn.md) to track AS number assignment for providers.
+
+### ASNs
+
+The [AS numbers](../ipam/asn.md) assigned to this provider (optional).
+
+### Account Number
+
+The administrative account identifier tied to this provider for your organization.
+
+### Portal URL
+
+The URL for the provider's customer service portal.
+
+### NOC Contact
+
+Contact details for the provider's network operations center (NOC).
+
+### Admin Contact
+
+Administrative contact details for the provider.

docs/models/circuits/providernetwork.md

@@ -2,4 +2,16 @@
 
 This model can be used to represent the boundary of a provider network, the details of which are unknown or unimportant to the NetBox user. For example, it might represent a provider's regional MPLS network to which multiple circuits provide connectivity.
 
-Each provider network must be assigned to a provider, and may optionally be assigned an arbitrary service ID. A circuit may terminate to either a provider network or to a site.
+## Fields
+
+### Provider
+
+The [provider](./provider.md) responsible for the operation of this network.
+
+### Name
+
+A human-friendly name, unique to the provider.
+
+### Service ID
+
+An arbitrary identifier used as an alternate reference for the type of connectivity or service being delivered.