Docker image guide

Added steps to setting up, creating, and running spyglass in Docker image

Change-Id: Ib168c12306608d19df66fc7961d1ceb28d46f5f1

README.rst

@@ -1,4 +1,3 @@
-
 What is Spyglass?
 -----------------
 

doc/source/cli.rst

@@ -1,19 +1,3 @@
-..
-      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 CLI
 ============

doc/source/developer_quickstart.rst

@@ -1,19 +1,3 @@
-..
-      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.
-
 ==========================
 Developer Quickstart Guide
 ==========================

doc/source/docker_guide.rst

@@ -0,0 +1,70 @@
+==================================
+Running Spyglass in a Docker Image
+==================================
+
+This is a guide to creating a docker image locally and running Spyglass in the
+docker image.
+
+1. Before creating the Spyglass image, ensure you have cloned Spyglass_,
+`Spyglass Excel plugin`_, and that you have installed `Docker CE`_.
+
+2. Update the Makefile with desired Linux distribution::
+
+    DISTRO=(ubuntu_xenial or ubuntu_bionic or opensuse_15)
+
+3. If necessary, change the PROXY variable to your proxy and change the
+USE_PROXY to true in the Makefile.
+
+4. Go to the Spyglass directory in Terminal and run ``make images``. When the
+build is done, you will see ``Successfully built <DOCKER_IMAGE>``
+
+5. From your home directory, create a new directory to store the output from
+docker with the following command:
+
+.. code-block:: bash
+
+    mkdir -p ~/tmp/spyglass
+
+6. Run Spyglass with the following command. The -v tag is used to mount the
+necessary local folders to the docker image . You must use the full path to the
+local folders you are mounting to. The path following the ':' is a path inside
+the docker container. These folders will be made automatically by docker. (The
+directory you are mounting to must be 'mnt' or another directory owned by
+airship user in the docker image)
+
+.. code-block:: bash
+
+    docker run -v /path/to/input/files:/mnt/input \
+    -v ~/tmp/spyglass:/mnt/output \
+    <DOCKER_IMAGE> spyglass excel documents -i \
+    -x /mnt/input/<excel_file_name> \
+    -e /mnt/input/<excel_spec_name> \
+    -c /mnt/input/<site_config_name> \
+    -s <site_name> -t /mnt/input/<templates_folder> \
+    -d /mnt/output -m /mnt/output
+
+Example
+^^^^^^^
+The following shows the command used to create the site manifest and
+intermediary in the docker container using the example files provided in
+Spyglass and the Spyglass Excel Plugin. (``/root/path/`` is the path to
+spyglass in your directory)
+
+.. code-block:: bash
+
+    docker run \
+    -v /root/path/spyglass/spyglass/examples/:/mnt/examples \
+    -v /root/path/spyglass-plugin-xls/spyglass_plugin_xls/examples:/mnt/examples_xls \
+    -v ~/tmp/spyglass:/mnt/output \
+    <DOCKER_IMAGE> spyglass excel documents -i \
+    -x /mnt/examples_xls/SiteDesignSpec_v0.1.xlsx \
+    -e /mnt/examples_xls/excel_spec.yaml \
+    -c /mnt/examples/site_config.yaml \
+    -s airship-seaworthy \
+    -t /mnt/examples/templates \
+    -d /mnt/output/ \
+    -m /mnt/output/
+
+.. _Spyglass: getting_started.html#basic-usage
+.. _`Spyglass Excel Plugin`: https://opendev.org/airship/spyglass-plugin-xls/src/branch/master/doc/source/getting_started.rst
+.. _`Docker CE`: https://docs.docker.com/install/

doc/source/getting_started.rst

@@ -1,19 +1,3 @@
-..
-      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
 ===============
@@ -65,11 +49,11 @@ Architecture
 
 Supported Features
 ------------------
-1. Spyglass Excel Plugin: https://opendev.org/airship/spyglass-plugin-xls
+1. `Spyglass Excel Plugin <https://opendev.org/airship/spyglass-plugin-xls>`_
 
 Future Work
 -----------
-1) Schema based manifest generation instead of Jinja2 templates. It shall
+1. Schema based manifest generation instead of Jinja2 templates. It shall
 be possible to cleanly transition to this schema based generation keeping a
 unique mapping between schema and generated manifests. Currently this is
 managed by considering a mapping of j2 templates with schemas and site type.
@@ -120,16 +104,20 @@ Basic Usage
 Before using Spyglass you must:
 
 
-1. Clone the Spyglass repository:
+1. Clone the Spyglass repository::
-
-   .. code-block:: console
 
     git clone https://opendev.org/airship/spyglass.git
 
-2. Install the required packages in Spyglass:
+2. Install the required packages in Spyglass::
-
-   .. code-block:: console
 
     pip3 install pipenv && pipenv install
 
+3. Launch the pipenv from your Spyglass directory::
+
+    pipenv shell
+
+4. Install Spyglass into the pipenv::
+
+    pip3 install .
+
 .. _airship-specs: https://airshipit.readthedocs.io/projects/specs/en/latest/specs/1.x/approved/data_config_generator.html

doc/source/index.rst

@@ -1,19 +1,3 @@
-..
-      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 Documentation
 ======================
@@ -45,4 +29,6 @@ engineer modify any data if required.
    getting_started
    developer_quickstart
    cli
+   docker_guide
+
 .. _spyglass-plugin-xls: https://opendev.org/airship/spyglass-plugin-xls