From e0651d4744d34259478bb6b6e698a6fe8753b9d1 Mon Sep 17 00:00:00 2001 From: "Daniel W. Anner" Date: Wed, 11 Jan 2023 15:37:55 -0500 Subject: [PATCH] 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 --- README.md | 108 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 74 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index 0848b6cac..97e2c4fca 100644 --- a/README.md +++ b/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.