mirror of
https://github.com/netbox-community/devicetype-library.git
synced 2024-11-22 00:13:36 +01:00
Documentation updates (#1053)
* - Added properties types, patterns, and options to the documentation - Added airflow property to documentation - Modified Component Definitions to have links to their anchor tags - Updated Pre-commit documentation to have better formatting and more information on usage and installation * testing example * Testing example admonition * Testing example admonition * Testing the first iteration of examples in the doc * Testing addition of required definitions * Testing addition of required definitions * Adding example of valid console-port * Removed console-ports example in favor of Wiki pages * Updated readme blockquote
This commit is contained in:
Daniel W. Anner
GitHub
parent
bec9c1d0b5
commit
e0651d4744
108
README.md
108
README.md
@ -15,41 +15,73 @@ that will check for duplicates, allow you to selectively import vendors, etc. av
|
||||
|
||||
## Device Type Definitions
|
||||
|
||||
Each definition must include at minimum the following fields:
|
||||
Each definition **must** include at minimum the following fields:
|
||||
|
||||
- `manufacturer`: The name of the manufacturer which produces this device type.
|
||||
- Type: String
|
||||
- `model`: The model number of the device type. This must be unique per manufacturer.
|
||||
- Type: String
|
||||
- `slug`: A URL-friendly representation of the model number. Like the model number, this must be unique per
|
||||
manufacturer.
|
||||
- Type: String
|
||||
- Pattern: `"^[-a-zA-Z0-9_]+$"`. Must match the following characters: `-`, `_`, Uppercase or Lowercase `a` to `z`, Numbers `0` to `9`.
|
||||
|
||||
The following fields may optionally be declared:
|
||||
>:test_tube: **Valid Example**:
|
||||
>```
|
||||
>manufacturer: Dell
|
||||
>model: PowerEdge R6515
|
||||
>slug: dell-poweredge-r6515
|
||||
>```
|
||||
|
||||
- `part_number`: An alternative representation of the model number (e.g. a SKU).
|
||||
- `u_height`: The height of the device type in rack units. Increments of 0.5U are supported. (Default: 1)
|
||||
- `is_full_depth`: A boolean which indicates whether the device type consumes both the front and rear rack faces.
|
||||
(Default: true)
|
||||
- `subdevice_role`: Indicates that this is a `parent` or `child` device. (Default: None)
|
||||
The following fields may **optionally** be declared:
|
||||
|
||||
- `part_number`: An alternative representation of the model number (e.g. a SKU). (**Default: None**)
|
||||
- Type: String
|
||||
> :test_tube: **Example**: `part_number: D109-C3`
|
||||
- `u_height`: The height of the device type in rack units. Increments of 0.5U are supported. (**Default: 1**)
|
||||
- Type: number (minimum of `0`, multiple of `0.5`)
|
||||
> :test_tube: **Example**: `u_height: 12.5`
|
||||
- `is_full_depth`: A boolean which indicates whether the device type consumes both the front and rear rack faces. (**Default: true**)
|
||||
- Type: Boolean
|
||||
> :test_tube: **Example**: `is_full_depth: false`
|
||||
- `airflow`: A decleration of the airflow pattern for the device. (**Default: None**)
|
||||
- Type: String
|
||||
- Options:
|
||||
- `front-to-rear`
|
||||
- `rear-to-front`
|
||||
- `left-to-right`
|
||||
- `right-to-left`
|
||||
- `side-to-rear`
|
||||
- `passive`
|
||||
> :test_tube: **Example**: `airflow: side-to-rear`
|
||||
- `subdevice_role`: Indicates that this is a `parent` or `child` device. (**Default: None**)
|
||||
- Type: String
|
||||
- Options:
|
||||
- `parent`
|
||||
- `child`
|
||||
> :test_tube: **Example**: `subdevice_role: parent`
|
||||
- `comments`: A string field which allows for comments to be added to the device. (**Default: None**)
|
||||
- Type: String
|
||||
> :test_tube: **Example**: `comments: This is a comment that will appear on all NetBox devices of this type`
|
||||
|
||||
For further detail on these attributes and those listed below, please reference the
|
||||
[schema definitions](schema/).
|
||||
[schema definitions](schema/) and the [Component Definitions](#component-definitions) below.
|
||||
|
||||
### Component Definitions
|
||||
|
||||
Valid component types are listed below. Each type of component must declare a list of the individual component templates
|
||||
to be added.
|
||||
|
||||
- `console-ports`
|
||||
- `console-server-ports`
|
||||
- `power-ports`
|
||||
- `power-outlets`
|
||||
- `interfaces`
|
||||
- `rear-ports`
|
||||
- `front-ports`
|
||||
- `module-bays`*
|
||||
- `device-bays`
|
||||
- `inventory-items`*
|
||||
|
||||
*Supported on NetBox v3.2 or later.
|
||||
- [`console-ports`](#console-ports "Availible in NetBox 2 and later")
|
||||
- [`console-server-ports`](#console-server-ports "Availible in NetBox 2.2 and later")
|
||||
- [`power-ports`](#power-ports "Availible in NetBox 1.7 and later")
|
||||
- [`power-outlets`](#power-outlets "Availible in NetBox 2 and later")
|
||||
- [`interfaces`](#interfaces "Availible in all versions of NetBox")
|
||||
- [`front-ports`](#front-ports "Availible in NetBox 2.5 and later")
|
||||
- [`rear-ports`](#rear-ports "Availible in NetBox 2.5 and later")
|
||||
- [`module-bays`](#module-bays "Availible in NetBox 3.2 and later")
|
||||
- [`device-bays`](#device-bays "Availible in all versions of NetBox")
|
||||
- [`inventory-items`](#inventory-items "Availible in NetBox 3.2 and later")
|
||||
|
||||
The available fields for each type of component are listed below.
|
||||
|
||||
@ -57,19 +89,19 @@ The available fields for each type of component are listed below.
|
||||
|
||||
- `name`: Name
|
||||
- `label`: Label
|
||||
- `type`: Port type slug (API value)
|
||||
- `type`: Port type slug (Array)
|
||||
|
||||
#### Console Server Ports
|
||||
|
||||
- `name`: Name
|
||||
- `label`: Label
|
||||
- `type`: Port type slug (API value)
|
||||
- `type`: Port type slug (Array)
|
||||
|
||||
#### Power Ports
|
||||
|
||||
- `name`: Name
|
||||
- `label`: Label
|
||||
- `type`: Port type slug (API value)
|
||||
- `type`: Port type slug (Array)
|
||||
- `maximum_draw`: The port's maximum power draw, in watts (optional)
|
||||
- `allocated_draw`: The port's allocated power draw, in watts (optional)
|
||||
|
||||
@ -77,7 +109,7 @@ The available fields for each type of component are listed below.
|
||||
|
||||
- `name`: Name
|
||||
- `label`: Label
|
||||
- `type`: Port type slug (API value)
|
||||
- `type`: Port type slug (Array)
|
||||
- `power_port`: The name of the power port on the device which powers this outlet (optional)
|
||||
- `feed_leg`: The phase (leg) of power to which this outlet is mapped; A, B, or C (optional)
|
||||
|
||||
@ -85,14 +117,14 @@ The available fields for each type of component are listed below.
|
||||
|
||||
- `name`: Name
|
||||
- `label`: Label
|
||||
- `type`: Interface type slug (API value)
|
||||
- `type`: Interface type slug (Array)
|
||||
- `mgmt_only`: A boolean which indicates whether this interface is used for management purposes only (default: false)
|
||||
|
||||
#### Front Ports
|
||||
|
||||
- `name`: Name
|
||||
- `label`: Label
|
||||
- `type`: Port type slug (API value)
|
||||
- `type`: Port type slug (Array)
|
||||
- `rear_port`: The name of the rear port on this device to which the front port maps
|
||||
- `rear_port_position`: The corresponding position on the mapped rear port (default: 1)
|
||||
|
||||
@ -100,7 +132,7 @@ The available fields for each type of component are listed below.
|
||||
|
||||
- `name`: Name
|
||||
- `label`: Label
|
||||
- `type`: Port type slug (API value)
|
||||
- `type`: Port type slug (Array)
|
||||
- `positions`: The number of front ports that can map to this rear port (default: 1)
|
||||
|
||||
#### Module Bays
|
||||
@ -125,11 +157,19 @@ The available fields for each type of component are listed below.
|
||||
|
||||
There are two ways this repo focuses on keeping quality device-type definitions:
|
||||
|
||||
- Pre-Commit Checks - Optional for helping to identify simple issues before committing. (trailing-whitespace, end-of-file-fixer, check-yaml, yamlfmt, yamllint)
|
||||
- [Install pre-commit](https://pre-commit.com/#install) (`pip install pre-commit`)
|
||||
- To install the pre-commit script `pre-commit install`
|
||||
- To run the pre-commit script on changed files `pre-commit run`
|
||||
- To run the pre-commit script on all files `pre-commit run --all`
|
||||
- To uninstall the pre-commit script `pre-commit uninstall`
|
||||
- **Pre-Commit Checks** - Optional, but **highly recommended**, for helping to identify simple issues before committing. (trailing-whitespace, end-of-file-fixer, check-yaml, yamlfmt, yamllint)
|
||||
- Installation
|
||||
- Virtual Environment Route
|
||||
- It is recommended to create a virtual env for your repo (`python3 -m venv venv`)
|
||||
- Install the required pip packages (`pip install -r requirements.txt`)
|
||||
- Continue to the "Install `pre-commit` Hooks"
|
||||
- `pre-commit` Only Route
|
||||
- [Install pre-commit](https://pre-commit.com/#install) (`pip install pre-commit`)
|
||||
- Install `pre-commit` Hooks
|
||||
- To install the pre-commit script: `pre-commit install`
|
||||
- Usage & Useful `pre-commit` Commands
|
||||
- After staging your files with `git`, to run the pre-commit script on changed files: `pre-commit run`
|
||||
- To run the pre-commit script on all files: `pre-commit run --all`
|
||||
- To uninstall the pre-commit script: `pre-commit uninstall`
|
||||
- Learn more about [pre-commit](https://pre-commit.com/)
|
||||
- GitHub Actions - Automatically run before a PR can be merged. Repeats yamllint & validates against NetBox Device-Type Schema.
|
||||
- **GitHub Actions** - Automatically run before a PR can be merged. Repeats yamllint & validates against NetBox Device-Type Schema.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user