Merge pull request #817 from jputrino/mitaka

Mitaka

.github/ISSUE_TEMPLATE.md

@@ -22,10 +22,10 @@
 <Fill in the OpenStack release, such as Liberty>
 
 #### Description
-<Describe the bug in detail, steps taken prior to encountering the issue, yand a short explanation of you have deployed openstack and F5® agent>
+<Describe the bug in detail, steps taken prior to encountering the issue, yand a short explanation of you have deployed openstack and F5 agent>
 
 #### Deployment
-<Explain in reasonable detail your OpenStack deployment, the F5® OpenStack agent, and BIG-IP®(s)>
-<Example: Single OpenStack controller with one F5® agent managing a cluster of 4 BIG-IP® VEs>
-<Example: Three OpenStack controllers in HA, each with one standalone F5® agent managing a single BIG-IP® appliance>
+<Explain in reasonable detail your OpenStack deployment, the F5 OpenStack agent, and BIG-IP(s)>
+<Example: Single OpenStack controller with one F5 agent managing a cluster of 4 BIG-IP VEs>
+<Example: Three OpenStack controllers in HA, each with one standalone F5 agent managing a single BIG-IP appliance>
 

.travis.yml

@@ -1,4 +1,4 @@
-sudo: true 
+sudo: required
 env:
   global:
     - DIST_REPO="f5-openstack-agent-dist"
@@ -15,7 +15,7 @@ python:
 before_install:
     - git config --global user.email "OpenStack_TravisCI@f5.com"
     - git config --global user.name "Travis F5 Openstack"
-
+    - docker pull f5devcentral/containthedocs:latest
 install:
     - pip install tox
 script:
@@ -25,6 +25,7 @@ script:
     - f5-openstack-agent-dist/scripts/package_agent.sh "ubuntu" "14.04"
     - sudo chown -R travis:travis ${DIST_REPO}/rpms/build
     - sudo chown -R travis:travis ${DIST_REPO}/deb_dist/*.deb
+    - ./docs/scripts/docker-docs.sh ./docs/scripts/test-docs.sh
 after_success:
   - md5sum ${PKG_RELEASE_EL7} > ${PKG_RELEASE_EL7}.md5 && md5sum --check ${PKG_RELEASE_EL7}.md5
   - md5sum ${PKG_RELEASE_1404} > ${PKG_RELEASE_1404}.md5 && md5sum --check ${PKG_RELEASE_1404}.md5
@@ -54,6 +55,26 @@ deploy:
       tags: true
       python: 2.7
     skip_cleanup: true
+  # deploy docs to s3
+  # if this is not a tagged release, the docs go to /products/openstack/agent/$TRAVIS_BRANCH
+  - provider: script
+    skip_cleanup: true
+    on:
+      repo: F5Networks/f5-openstack-agent
+      branch: mitaka
+      condition: $TRAVIS_TAG = ""
+    script:
+    - ./docs/scripts/deploy-docs.sh publish-product-docs-to-prod openstack/agent $TRAVIS_BRANCH
+  # if this is a tagged release, the docs go to /products/openstack/agent/$TRAVIS_BRANCH/vX.Y
+  - provider: script
+    skip_cleanup: true
+    env:
+    - RELEASE_TAG="$(echo $TRAVIS_TAG |cut -c1-4)"
+    on:
+      tags: true
+      repo: F5Networks/f5-openstack-agent
+    script:
+    - ./docs/scripts/deploy-docs.sh publish-product-docs-to-prod openstack/agent/$TRAVIS_BRANCH $RELEASE_TAG
 
 notifications:
   slack:

CONTRIBUTING.md

@@ -58,7 +58,7 @@ $ py.test --cov ./ --cov-report=html
 $ open htmlcov/index.html
 ```
 
-If you are running our functional tests you will need a real BIG-IP® to run 
+If you are running our functional tests you will need a real BIG-IP to run 
 them against; you can get one of those pretty easily in [Amazon EC2](https://aws.amazon.com/marketplace/pp/B00JL3UASY/ref=srh_res_product_title?ie=UTF8&sr=0-10&qid=1449332167461).
 
 ## License
@@ -77,4 +77,4 @@ See the License for the specific language governing permissions and
 limitations under the License.
 
 ### Contributor License Agreement
-Individuals or business entities who contribute to this project must have completed and submitted the [F5® Contributor License Agreement](http://f5-openstack-docs.readthedocs.org/en/latest/cla_landing.html#cla-landing) to Openstack_CLA@f5.com prior to their code submission being included in this project.
+Individuals or business entities who contribute to this project must have completed and submitted the [F5 Contributor License Agreement](http://f5-openstack-docs.readthedocs.org/en/latest/cla_landing.html#cla-landing) to Openstack_CLA@f5.com prior to their code submission being included in this project.

Makefile

@@ -0,0 +1,20 @@
+# Makefile for building and testing documentation in a docker container
+#
+
+.PHONY: help
+help:
+	@echo "  docker-preview     to build live preview of docs using sphinx-autobuild in a docker container"
+	@echo "  docker-test        to build and test docs in a docker container"
+
+# Build live preview docs in a docker container
+.PHONY: docker-preview
+docker-preview:
+	make -C docs clean
+	DOCKER_RUN_ARGS="-p 0.0.0.0:8000:8000" ./docs/scripts/docker-docs.sh \
+	  make -C docs preview
+
+# run quality tests in a docker container
+.PHONY: docker-test
+docker-test:
+	make -C docs clean
+	./docs/scripts/docker-docs.sh ./docs/scripts/test-docs.sh

README.rst

@@ -1,7 +1,7 @@
 .. raw:: html
 
    <!--
-   Copyright 2015-2016 F5 Networks Inc.
+   Copyright 2015-2017 F5 Networks Inc.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
@@ -16,134 +16,172 @@
    limitations under the License.
    -->
 
-f5-openstack-agent
-##################
+F5 Agent for OpenStack Neutron
+==============================
 
 |Build Status| |slack badge| |coveralls badge|
 
+
+version |release|
+-----------------
+
+
 Introduction
-************
+------------
 
-The F5® agent translates from 'OpenStack' to 'F5®'. It uses the `f5-sdk <http://f5-sdk.readthedocs.io>`_ to translate OpenStack messaging calls -- such as those from the Neutron RPC messaging queue -- into iControl® REST calls to F5® technologies, such as BIG-IP®.
+The F5 Agent for OpenStack Neutron is an OpenStack `Neutron plugin agent <https://docs.openstack.org/admin-guide/networking-arch.html#overview>`_. It works in conjunction with the `F5 driver for OpenStack LBaaSv2 <http://clouddocs.f5.com/products/openstack/lbaasv2-driver/latest/index.html>`_ to manage F5 BIG-IP `Local Traffic Manager <https://f5.com/products/big-ip/local-traffic-manager-ltm>`_ (LTM) services via the OpenStack Neutron API.
 
 Documentation
-*************
+-------------
 
-Documentation is published on Read the Docs, at http://f5-openstack-agent.readthedocs.io.
+Documentation is published on `clouddocs.f5.com <http://clouddocs.f5.com/products/openstack/agent/latest>`_.
 
 Compatibility
-*************
+-------------
 
-The F5® OpenStack agent is compatible with OpenStack releases from Liberty forward. If you are using Kilo or earlier, you'll need the `LBaaSv1 plugin <http://f5-openstack-lbaasv1.readthedocs.io>`_.
+The F5 Agent for OpenStack Neutron is compatible with OpenStack releases from Liberty forward.
 
-See the `F5® OpenStack Releases and Support Matrix <http://f5-openstack-docs.readthedocs.org/en/latest/releases_and_versioning.html>`_ for more information.
+See the `F5 OpenStack Releases and Support Matrix <http://clouddocs.f5.com/cloud/openstack/latest/support/releases_and_versioning.html>`_ for more information.
 
-Installation
-************
+Installing the F5 Agent
+-----------------------
 
-Please see the `documentation <http://f5-openstack-agent.readthedocs.io>`_ for installation instructions.
+Please see `installing the F5 agent </docs/README.rst#installation>`_.
 
-For Developers
-**************
 
-Filing Issues
-=============
+Using the Built-in Debugger
+---------------------------
 
-If you find an issue, we would love to hear about it. Please open a new `issue <https://github.com/F5Networks/f5-openstack-agent/issues>`_ aissue for each bug you'd like to report or feature you'd like to request. Please be specific, and include as much information about your environment and the issue as possible.
+Use the built-in debugger -- ``debug_bundler.py`` -- to package information about your environment for debugging purposes.
 
-Contributing
-************
-See `Contributing <CONTRIBUTING.md>`_.
+When the you install ``f5-openstack-agent``, the ``debug_bundler.py`` script installs itself in ``/usr/bin/f5/``.
+When you run the debugger, it searches for log and config files and dumps a complete listing of the ``pip lists`` output.
+The debugger bundles everything it finds into a tarfile that you can provide to F5's support representatives to assist them in identifying the cause of your issue.
 
-Test
-****
-Before you open a pull request, your code must have passing
-`pytest <http://pytest.org>`__ unit tests. In addition, you should
-include a set of functional tests written to use a real BIG-IP® device
-for testing. Information on how to run our set of tests is included
-below.
+-------------
 
-Style Checks
-============
+**WARNING**
 
-We use the hacking module for our style checks.
+The files added to the debug bundle may contain **VERY SENSITIVE INFORMATION** such as **encryption keys**, **passwords**, and **usernames**.
+Do not upload this bundle, or any information within, to a public forum unless you have thoroughly scrubbed sensitive information.
+When in doubt, don't upload it at all.
 
-::
-    $ pip install tox
-    $ tox -e style
+-------------
 
-Unit Tests
-==========
 
-We use tox to run our pytest unit tests. To run the unit tests use the tox
-environment `unit`.
+Basic usage with the default command-line arguments
+```````````````````````````````````````````````````
+
+The command below creates a .tar file in the specified directory (in this example, `/home/myuser/debug_bundle_output/`) containing all logs and configuration files the script found.
+The script offers a best-effort search of the specified directories.
+If it cannot find the log files it is looking for in those directories, it prints an error message and continues to run.
+
 
 ::
-    $ pip install tox
-    $ tox -e unit
 
-Functional Tests
-=================
+  $ python /usr/bin/f5/debug_bundler.py /home/myuser/debug_bundle_output/
 
-Functional tests can be run without a full OpenStack deployment, but do require
-access to a BIG-IP device or VE instance.
 
-1. Create a symbol's file that describes the environment that you are running
-   your test in by copying and editing the `symbols.json.example <test/functional/symbols.json.example>`_
-   file to have the values that are correct for your BIG-IP.
 
-2. Run the functional tests by supplying the symbol file that you just created
-   which includes the information relative to your environment using the
-   example file. The example below runs the disconnected services neutronless
-   functional test cases (the tox target changes to the [test/functional](test/functional)
-   directory before running.
+Override log/config file locations
+``````````````````````````````````
 
-::
+The default log location is `/var/log/neutron`.
+The default configuration file location is `/etc/neutron`.
 
-    $ tox -e functest -- \
-      --symbols ~/path/to/symbols/symbols.json \
-      neutronless/disconnected_service
+To override the log and/or config file locations, use the command-line arguments shown below: ::
 
-Troubleshooting
-===============
+  $ python /usr/bin/f5/debug_bundler.py --log-dir=/var/log/mylogs --config-dir /etc/myconfigs/ ~/
 
-When the f5-openstack-agent is installed, the *debug_bundler.py* script will be installed to */usr/bin/f5/*. This script can be run from the command line directly. It will search in the specified directories to bundle log files and configuration files for use in debugging an issue with the f5-openstack-agent. In addition to the above files, it also dumps a complete listing of the ``pip lists`` output.
 
-**WARNING**
+Issues
+``````
+
+If you find any issues with the debug_bundler, please `file an issue <#filing-issues>`_.
+
+
+For Developers
+--------------
+
+Filing Issues
+`````````````
+
+If you find an issue, we would love to hear about it.
+Please file an `issue <https://github.com/F5Networks/f5-openstack-agent/issues>`_ in this repository.
+Use the issue template to tell us as much as you can about what you found, how you found it, your environment, etc.
+Admins will triage your issue and assign it for a fix based on the priority level assigned.
+We also welcome you to file issues for feature requests.
+
+Contributing
+````````````
+
+See `Contributing <CONTRIBUTING.md>`_.
 
-The files added to this bundle may contain VERY SENSITIVE INFORMATION such as encryption keys, passwords, and usernames. Do not upload this bundle, or any information within, to a public forum unless you have scrubbed sensitive information thoroughly. When in doubt, don't upload it at all.
+Testing
+```````
 
-Below you can see the basic usage, using the default command-line arguments:
+Before you open a pull request, your code must have passing `pytest <http://pytest.org>`__ unit tests.
+In addition, you should include a set of functional tests written to use an actual BIG-IP device for testing.
+Information on how to run our test set is included below.
+
+Style Checks
+~~~~~~~~~~~~
+
+We use the ``hacking`` module for our style checks.
 
 ::
 
-    $ python /usr/bin/f5/debug_bundler.py /home/myuser/debug_bundle_output/
+  $ pip install tox
+  $ tox -e style
+
+Unit Tests
+~~~~~~~~~~
 
-A tarred, compressed, file will be created in the directory specified. It will contain all logs and configuration files the script found. Note that the script offers a best-effort search of the directories given, and if it cannot find the log files it is looking for in those directories, it will print a message and continue running.
+We use ``tox`` to run our ``pytest`` unit tests.
 
-The default log location is set to `/var/log/neutron` and the default configuration file location is in `/etc/neutron`. These locations can be overriden via the command-line invocation shown below:
+To run the unit tests, use the ``tox`` ``unit`` environment.
 
 ::
 
-    $ python /usr/bin/f5/debug_bundler.py --log-dir=/var/log/mylogs --config-dir /etc/myconfigs/ ~/
+  $ pip install tox
+  $ tox -e unit
+
+Functional Tests
+~~~~~~~~~~~~~~~~
+
+You can run functional tests without a full OpenStack deployment.
+They do require access to a BIG-IP device or BIG-IP Virtual Edition (VE) instance.
+
+#. Copy and edit the `symbols.json.example <test/functional/symbols.json.example>`_ with the correct values for your BIG-IP device.
+
+#. Run ``tox -e functest`` with the ``--symbols`` flag pointing to your updates symbols.json file.
+
+   For example, the command below calls the symbols file and runs the ``neutronless/disconnected_service`` functional test cases.
+   The ``tox`` target changes to the ``[test/functional](test/functional)`` directory before the tests run.
+
+::
+
+  $ tox -e functest -- \
+    --symbols ~/path/to/symbols/symbols.json \
+    neutronless/disconnected_service
+
 
-If any issue is found with the debug_bundler script, please file an issue on GitHub.
 
 Copyright
-*********
+---------
 
-Copyright 2015-2016 F5 Networks Inc.
+Copyright 2015-2017 F5 Networks Inc.
 
 Support
-*******
+-------
 
 See `Support <SUPPORT.md>`_.
 
 License
-*******
+-------
 
 Apache V2.0
-===========
+```````````
 
 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
@@ -158,9 +196,9 @@ See the License for the specific language governing permissions and
 limitations under the License.
 
 Contributor License Agreement
-=============================
+-----------------------------
 
-Individuals or business entities who contribute to this project must have completed and submitted the `F5® Contributor License Agreement <http://f5-openstack-docs.readthedocs.org/en/latest/cla_landing.html#cla-landing>`_ to Openstack\_CLA@f5.com prior to their code submission being included in this project.
+Individuals or business entities who contribute to this project must complete and submit the `F5 Contributor License Agreement <http://f5-openstack-docs.readthedocs.org/en/latest/cla_landing.html#cla-landing>`_ to Openstack\_CLA@f5.com **before** their code submission can be added to this project.
 
 
 .. |Build Status| image:: https://travis-ci.org/F5Networks/f5-openstack-agent.svg?branch=liberty

SUPPORT.md

@@ -1,6 +1,6 @@
 Maintenance and F5 Technical Support of the F5 code is provided only if the 
 software (i) is unmodified; and (ii) has been marked as F5 Supported in 
-SOL80012344, (https://support.f5.com/kb/en-us/solutions/public/k/80/sol80012344.html). 
+SOL80012344, (https://support.f5.com/csp/article/K80012344). 
 Support will only be provided to customers who have an existing support contract, 
 purchased separately, subject to F5’s support policies available at 
 http://www.f5.com/about/guidelines-policies/ and http://askf5.com.

docs/Makefile

@@ -47,6 +47,7 @@ help:
 	@echo "  linkcheck  to check all external links for integrity"
 	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
 	@echo "  coverage   to run coverage check of the documentation (if enabled)"
+	@echo "  preview    to build local preview of docs using sphinx-autobuild"
 
 .PHONY: clean
 clean:
@@ -221,3 +222,11 @@ pseudoxml:
 	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
 	@echo
 	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
+
+# build live preview docs locally
+.PHONY: preview
+preview:
+	@echo "Running autobuild. View live edits at:"
+	@echo "  http://0.0.0.0:8000/index.html"
+	@echo ""
+	sphinx-autobuild --host 0.0.0.0 -b html ./ $(BUILDDIR)