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