From f9df9d1886623bc322d08f7a850843aebc0ba8ab Mon Sep 17 00:00:00 2001 From: Ryan Schroder Date: Mon, 16 Dec 2019 10:08:40 -0600 Subject: [PATCH] Docs update for Spyglass Excel Plugin Removed all tugboat refernces, added getting started guide to explain installation and steps to run, and reformated so that all the informantion was not in the index file. Change-Id: I20234c1c7565794d81d25565fddb2879df460d9b --- README.rst | 26 +++++- doc/source/excel_specification.rst | 141 +++++++++++++++++++++++++++++ doc/source/getting_started.rst | 74 +++++++++++++++ doc/source/index.rst | 111 +++-------------------- 4 files changed, 247 insertions(+), 105 deletions(-) create mode 100644 doc/source/excel_specification.rst create mode 100644 doc/source/getting_started.rst diff --git a/README.rst b/README.rst index 8acd160..08317e1 100644 --- a/README.rst +++ b/README.rst @@ -1,10 +1,26 @@ +.. + Copyright 2019 AT&T Intellectual Property. + All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + Spyglass Excel Plugin --------------------- -Tugboat is a Spyglass plugin to generate airship-seaworthy site manifest files -from an excel based engineering spec. The plugin is configured with an Excel -sheet and its corresponding excel specification as inputs. Spyglass uses this -plugin to construct an intermediary yaml which is processed further using J2 -templates to generate site manifests. +The Spyglass Excel Plugin is used to generate airship-seaworthy site +manifest files from an excel based engineering spec. The plugin is +configured with an Excel sheet and its corresponding excel specification as +inputs. Spyglass uses this plugin to construct an intermediary yaml which is +processed further using J2 templates to generate site manifests. Spyglass: https://opendev.org/airship/spyglass diff --git a/doc/source/excel_specification.rst b/doc/source/excel_specification.rst new file mode 100644 index 0000000..793a85b --- /dev/null +++ b/doc/source/excel_specification.rst @@ -0,0 +1,141 @@ +.. + Copyright 2019 AT&T Intellectual Property. + All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +=================== +Excel Specification +=================== + +Excel Spec is like an index to the Excel sheet to look for the data to be +collected by the tool. The excel_spec.yaml file provides a sample structure for +an excel specification based off the SiteDesignSpec_v0.1.xlsx sheet. (Both can +be found in the examples folder) + +Below is the definition for each key in the Excel spec + ++ **ipmi** + + * type - How the data is stored (series/container/point) + * sheet_name - Name of the sheet from where IPMI information is to be read + (File name, excluding the file extension, when using a CSV file) + * iter + + + index-type - How data is indexed (row/col) + + start - Row/Col number where ipmi data begins + + end - Row/Col number where ipmi data ends + + * data + + + hostname - location of the hostname (row/col/[r, c]) + + ipmi_address - location of the ipmi address (row/col/[r, c]) + + ipmi_gateway - location of the ipmi gateway (row/col/[r, c]) + + host_profile - location of the host profile (row/col/[r, c]) + ++ **private_vlan** + + * type - How the data is stored (series/container/point) + * sheet_name - Name of the sheet from where private vlan information is to + be read (File name, excluding the file extension, when using a CSV file) + * no_sanitize - Names of values that should not be sanitized + * iter + + + index-type - How data is indexed (row/col) + + start - Row/Col number where private vlan data begins + + end - Row/Col number where private vlan data ends + + * data + + + net_type - location of the net type (row/col/[r, c]) + + vlan - location of the vlan (row/col/[r, c]) + ++ **private_net** + + * type - How the data is stored (series/container/point) + * sheet_name - Name of the sheet from where private net information is to + be read (File name, excluding the file extension, when using a CSV file) + * iter + + + index-type - How data is indexed (row/col) + + start - Row/Col where private vlan data begins + + end - Row/Col where private vlan data ends + + * data + + + vlan - location of the vlan (row/col/[r, c]) + + ip - location of the ip (row/col/[r, c]) + ++ **public** + + * type - How the data is stored (series/container/point) + * sheet_name - Name of the sheet from where public information is to be + read (File name, excluding the file extension, when using a CSV file) + * data + + + oam + + * type - How the data is stored (series/container/point) + * data + + + vlan - location of the vlan (row/col/[r, c]) + + ip - location of the ip (row/col/[r, c]) + + + ingress + + * type - How the data is stored (series/container/point) + * data + + + ip - location of the ip (row/col/[r, c]) + + + oob + + * type - How the data is stored (series/container/point) + * iter + + + index-type - How data is indexed (row/col) + + start - Row/Col where private vlan data begins + + end - Row/Col where private vlan data ends + + * data + + + ip - location of the ip (row/col/[r, c]) + ++ **site_info** + + * type - How the data is stored (series/container/point) + * sheet_name - Name of the sheet from where site information is to be read + (File name, excluding the file extension, when using a CSV file) + * sanitize - If data should be sanitised (boolean) + * data + + + domain - location of the domain (row/col/[r, c]) + + subdomain - location of the subdomain (row/col/[r, c]) + + global_group - location of the global group (row/col/[r, c]) + + ldap - location of the ldap (row/col/[r, c]) + + ntp - location of the ntp (row/col/[r, c]) + + dns - location of the dns (row/col/[r, c]) + ++ **location** + + * type - How the data is stored (series/container/point) + * sheet_name - Name of the sheet from where location information is to be + read (File name, excluding the file extension, when using a CSV file) + * sanitize - If data should be sanitised (boolean) + * data + + + sitename - location of the sitename (row/col/[r, c]) + + corridor - location of the corridor (row/col/[r, c]) + + state - location of the state (row/col/[r, c]) + + country - location of the country (row/col/[r, c]) + + clli - location of the clli (row/col/[r, c]) diff --git a/doc/source/getting_started.rst b/doc/source/getting_started.rst new file mode 100644 index 0000000..57dda63 --- /dev/null +++ b/doc/source/getting_started.rst @@ -0,0 +1,74 @@ +.. + Copyright 2019 AT&T Intellectual Property. + All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +=============== +Getting Started +=============== + +This document explains the steps to installing and setting up the Spyglass +Excel plugin. + +1.) Clone the Spyglass Excel plugin:: + + git clone https://opendev.org/airship/spyglass-plugin-xls.git + +2.) Clone Spyglass:: + + git clone https://opendev.org/airship/spyglass.git + +3.) Install required packages in Spyglass directory:: + + pip3 install pipenv && pipenv install + +4.) Launch the pipenv from your spyglass directory:: + + pipenv shell + +5.) Install Spyglass and the Spyglass Excel plugin into the pipenv:: + + pip3 install . && pip3 install ../spyglass-plugin-xls/. + +6.) You can now run Spyglass commands from the pipenv. + +Examples +-------- + +1. Required Input (Refer to 'spyglass_plugin_xls/examples' folder to get these +inputs) + + a) Excel File: SiteDesignSpec_v0.1.xlsx + b) Excel Spec: excel_spec_upstream.yaml + c) Site Config: 'spyglass/examples/site_config.yaml' + d) Template_dir: 'spyglass/examples/templates' + e) Site name: airship-seaworthy + +2. Spyglass CLI Command using an Excel File: + +.. code-block:: bash + + spyglass excel documents -i -x ../spyglass-plugin-xls/spyglass_plugin_xls/examples/SiteDesignSpec_v0.1.xlsx \ + -e ../spyglass-plugin-xls/spyglass_plugin_xls/examples/excel_spec.yaml \ + -c ../spyglass-plugin-xls/spyglass_plugin_xls/examples/site_config.yaml \ + -s airship-seaworthy -t spyglass/examples/templates/ + +3. Spyglass CLI Command using a CSV File: + +.. code-block:: bash + + spyglass excel documents -i -x ../spyglass-plugin-xls/spyglass_plugin_xls/examples/Site-Information.csv \ + -e ../spyglass-plugin-xls/spyglass_plugin_xls/examples/excel_spec.yaml \ + -c ../spyglass-plugin-xls/spyglass_plugin_xls/examples/site_config.yaml \ + -s airship-seaworthy -t spyglass/examples/templates/ diff --git a/doc/source/index.rst b/doc/source/index.rst index 2aa9c51..b2ecaa8 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -14,109 +14,20 @@ License for the specific language governing permissions and limitations under the License. -.. _tugboatinfo: +===================== +Spyglass Excel Plugin +===================== -=================== -Spyglass XLS Plugin -=================== - -What is the Spyglass XLS Plugin? --------------------------------- - -The Spyglass XLS plugin is used to generate airship-seaworthy site manifest -files from an excel based engineering spec. The plugin is configured with an +Overview +-------- +The Spyglass Excel plugin is used to generate airship-seaworthy site manifest +files from an Excel based engineering spec. The plugin is configured with an Excel sheet or a CSV file and its corresponding excel specification as inputs. Spyglass uses this plugin to construct an intermediary yaml which is processed further using Jinja2 templates to generate site manifests. -Excel Specification -------------------- -Excel Spec is like an index to the Excel sheet to look for the data to be -collected by the tool. Excel Spec Sample specifies all the details that -need to be filled by the Deployment Engineer. +.. toctree:: + :maxdepth: 2 -Below is the definition for each key in the Excel spec - -* ipmi_sheet_name - name of the sheet from where IPMI and host profile - information is to be read (File name, excluding the file extension, when - using a CSV file) -* start_row - row number from where the IPMI and host profile information - starts -* end_row - row number from where the IPMI and host profile information ends -* hostname_col - column number where the hostnames are to be read from -* ipmi_address_col - column number from where the ipmi addresses are to be read -* host_profile_col - column number from where the host profiles are to be read -* ipmi_gateway_col - column number from where the ipmi gateways are to be read -* private_ip_sheet - name of the sheet which has the private IP information -* net_type_col - column number from where the network type is to be read -* vlan_col - column number from where the network vlan is to be read -* vlan_start_row - row number from where the vlan information starts -* vlan_end_row - row number from where the vlan information ends -* net_start_row - row number from where the network information starts -* net_end_row - row number from where the network information ends -* net_col - column number where the IP ranges for network is to be read -* net_vlan_col - column number where the vlan information is present in the - pod wise network section -* public_ip_sheet - name of the sheet which has the public IP information -* oam_vlan_col - column number from where the OAM vlan information is to be - read from -* oam_ip_row - row number from where the OAM network information is to be read - from -* oam_ip_col - column number from where the OAM network information is to be - read from -* oob_net_row - row number which has the OOB network subnet ranges -* oob_net_start_col - column number from where the OOB network ranges start -* oob_net_end_col - column number from where the OOB network ranges end -* ingress_ip_row - row number from where the Ingress network information is to - be read from -* dns_ntp_ldap_sheet - name of the sheet which has the DNS, NTP and LDAP - information -* login_domain_row - row number which has the ldap login domain -* ldap_col - column number which has the all ldap related information -* global_group - row number which has the ldap group information -* ldap_search_url_row - row number which has the ldap url -* ntp_row - row number which has the ntp information -* ntp_col - column number which has the ntp information -* dns_row - row number which has the dns information -* dns_col - column number which has the dns information -* domain_row - row number which has the domain information -* domain_col - column number which has the domain information -* location_sheet - name of the sheet which has the location information -* column - column number which has all the information -* corridor_row - row number which has the corridor information -* site_name_row - row number which has the site name -* state_name_row - row number which has the state name -* country_name_row - row number which has the country name -* clli_name_row - row number which has CLLI information - -Example: Spyglass XLS Plugin Usage ----------------------------------- - -1. Required Input (Refer to 'spyglass_plugin_xls/examples' folder to get these -inputs) - - a) Excel File: SiteDesignSpec_v0.1.xlsx - b) Excel Spec: excel_spec_upstream.yaml - c) Site Config: site_config.yaml - d) Template_dir: 'spyglass/examples/templates' - e) Site name: airship-seaworthy - -2. Spyglass CLI Command using an Excel File: - -.. code-block:: bash - - spyglass excel documents -i \ - -x ../spyglass-plugin-xls/spyglass_plugin_xls/examples/SiteDesignSpec_v0.1.xlsx \ - -e ../spyglass-plugin-xls/spyglass_plugin_xls/examples/excel_spec.yaml \ - -c ../spyglass-plugin-xls/spyglass_plugin_xls/examples/site_config.yaml \ - -s airship-seaworthy -t spyglass/examples/templates/ - -3. Spyglass CLI Command using a CSV File: - -.. code-block:: bash - - spyglass excel documents -i \ - -x ../spyglass-plugin-xls/spyglass_plugin_xls/examples/Site-Information.csv \ - -e ../spyglass-plugin-xls/spyglass_plugin_xls/examples/excel_spec.yaml \ - -c ../spyglass-plugin-xls/spyglass_plugin_xls/examples/site_config.yaml \ - -s airship-seaworthy -t spyglass/examples/templates/ \ No newline at end of file + getting_started + excel_specification