[docs] Armada documentation warning-is-error True.

This PS adds warning-is-error = 1 under [build_sphinx] in setup.cfg
so that warnings can be caught.

A number of warnings/errors while building the docs are have been
corrected by this PS as well.

Change-Id: I445369c802e559c629a685024575bd562ea05a1b

.gitignore

@@ -62,7 +62,8 @@ instance/
 .scrapy
 
 # Sphinx documentation
-docs/_build/
+docs/build/
+docs/source/_static
 
 # PyBuilder
 target/
@@ -88,4 +89,3 @@ ENV/
 
 # Rope project settings
 .ropeproject
-

README.rst

@@ -12,7 +12,7 @@ Roadmap
 
 Detailed roadmap can be viewed `here <https://github.com/att-comdev/armada/milestones>`_
 
-Issues can be reported `here <https://github.com/att-comdev/armada/issues>`_
+Issues can be reported `on GitHub <https://github.com/att-comdev/armada/issues>`_
 
 Installation
 ------------
@@ -26,7 +26,7 @@ Using armada `docs <docs/source/operations/guide-use-armada.rst>`_
 Getting Started
 ---------------
 
-Get started guide can be found in our `docs <docs/source/development/getting-started.rst>`_
+Get started guide can be found in our `Getting Started docs <docs/source/development/getting-started.rst>`_
 
 Usage
 -----

docs/source/conf.py

@@ -19,7 +19,6 @@
 # import os
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
-import sphinx_rtd_theme
 
 
 # -- General configuration ------------------------------------------------
@@ -31,10 +30,25 @@ import sphinx_rtd_theme
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = []
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.todo',
+    'sphinx.ext.viewcode',
+    'oslo_config.sphinxconfiggen',
+    'oslo_policy.sphinxpolicygen'
+]
+
+# oslo_config.sphinxconfiggen options
+config_generator_config_file = '../../etc/armada/config-generator.conf'
+sample_config_basename = '_static/armada'
+
+# oslo_policy.sphinxpolicygen options
+
+policy_generator_config_file = '../../etc/armada/policy-generator.conf'
+sample_policy_basename = '_static/armada'
 
 # Add any paths that contain templates here, relative to this directory.
-# templates_path = ['_templates']
+# templates_path = []
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
@@ -83,7 +97,8 @@ todo_include_todos = False
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_rtd_theme'
+import sphinx_rtd_theme
+html_theme = "sphinx_rtd_theme"
 html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 # Theme options are theme-specific and customize the look and feel of a theme
@@ -95,7 +110,7 @@ html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-# html_static_path = ['_static']
+html_static_path = ['_static']
 
 
 # -- Options for HTMLHelp output ------------------------------------------
@@ -150,6 +165,6 @@ man_pages = [
 #  dir menu entry, description, category)
 texinfo_documents = [
     (master_doc, 'Armada', u'Armada Documentation',
-     author, 'Armada', 'One line description of project.',
+     author, 'Armada', 'A python REST orchestrator.',
      'Miscellaneous'),
 ]

docs/source/development/contributing.rst

@@ -0,0 +1 @@
+.. include:: ../../../CONTRIBUTING.rst

docs/source/development/index.rst

@@ -11,4 +11,4 @@ Developers Guide
    :caption: Contents:
 
    getting-started.rst
-   ../../../CONTRIBUTING.rst
+   contributing.rst

docs/source/index.rst

@@ -15,8 +15,6 @@ Welcome to Armada's documentation!
    operations/index
    commands/index
 
-
-
 Indices and tables
 ==================
 

docs/source/operations/guide-api.rst

@@ -19,26 +19,26 @@ Armada Endpoints
     :>json float timeout
 
 
-.. code-block:: json
+::
 
     Request:
 
     {
-    	"file": "examples/openstack-helm.yaml",
-    	"options": {
-    		"debug": true,
-    		"disable_update_pre": false,
-    		"disable_update_post": false,
-    		"enable_chart_cleanup": false,
-    		"skip_pre_flight": false,
-    		"dry_run": false,
-    		"wait": false,
-    		"timeout": false
-    	}
+        "file": "examples/openstack-helm.yaml",
+        "options": {
+            "debug": true,
+            "disable_update_pre": false,
+            "disable_update_post": false,
+            "enable_chart_cleanup": false,
+            "skip_pre_flight": false,
+            "dry_run": false,
+            "wait": false,
+            "timeout": false
+        }
     }
 
 
-.. code-block:: json
+::
 
     Results:
 
@@ -56,7 +56,7 @@ Tiller Endpoints
     Description: Retrieves tiller releases.
 
 
-.. code-block:: json
+::
 
     Results:
 
@@ -78,7 +78,7 @@ Tiller Endpoints
     Retrieves the status of the Tiller server.
 
 
-.. code-block:: json
+::
 
     Results:
 

docs/source/operations/guide-build-armada-yaml.rst

@@ -25,7 +25,7 @@ armada/Manifest/v1
 +---------------------+--------+----------------------+
 
 Example
-~~~~~~~~
+^^^^^^^
 
 ::
 
@@ -56,7 +56,7 @@ armada/ChartGroup/v1
 +-----------------+----------+------------------------------------------------------------------------+
 
 Example
-~~~~~~~~
+^^^^^^^
 
 ::
 
@@ -153,7 +153,7 @@ Update - Actions - Update/Delete
    Delete Actions only support type: 'job'
 
 Example
-~~~~~~~
+^^^^^^^
 
 ::
 
@@ -244,7 +244,7 @@ Source
 
 
 Example
-~~~~~~~
+^^^^^^^
 
 ::
 
@@ -323,7 +323,7 @@ Armada - Deploy Behavior
     the size of the chart definition will show example in multichart below
 
 Simple Example
-~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^
 
 ::
 
@@ -364,7 +364,7 @@ Simple Example
         - blog-group
 
 Multichart Example
-~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^
 
 ::
 

docs/source/operations/guide-exceptions.rst

@@ -52,7 +52,7 @@ Chartbuilder Exceptions
 +-----------------------------+-------------------------------------------------------------+
 
 Source Exceptions
-===============
+=================
 
 +--------------------------+---------------------------------------------------------------------+
 | Exception                | Error Description                                                   |

docs/source/operations/guide-helm-plugin.rst

@@ -1,5 +1,5 @@
 Armada Plugin
-============
+=============
 
 The armada plugin extends all the functionality of Armada to be used as a plugin with Helm.
 

docs/source/operations/guide-troubleshooting.rst

@@ -53,5 +53,5 @@ Issue
 -----
 
 If the issue that you are having does not appear here please check the aramda
-issues `here <https://github.com/att-comdev/armada/issues>`_. If the issue does
-not exist, please create an issue. 
+issues `section <https://github.com/att-comdev/armada/issues>`_. If the issue does
+not exist, please create an issue.

docs/source/operations/guide-use-armada.rst

@@ -6,9 +6,9 @@ Prerequisites
 
 Kubernetes Cluster
 
-Tiller Service `here <http://github.com/kubernetes/helm>`_
+`Tiller Service <http://github.com/kubernetes/helm>`_
 
-Armada.yaml `here <guide-build-armada-yaml.rst>`_
+`Armada.yaml <guide-build-armada-yaml.rst>`_
 
 .. note::
 

docs/source/operations/index.rst

@@ -15,3 +15,7 @@ Operations Guide
    guide-configure.rst
    guide-troubleshooting.rst
    guide-use-armada.rst
+   guide-exceptions.rst
+   guide-helm-plugin.rst
+   sampleconf.rst
+   samplepolicy.rst

docs/source/operations/sampleconf.rst

@@ -0,0 +1,26 @@
+..
+    Copyright 2017 AT&T Intellectual Property.  All other 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.
+
+Sample Configuration File
+==========================
+
+The following is a sample Armada configuration for adaptation and use. It is
+auto-generated from Armada when this documentation is built, so
+if you are having issues with an option, please compare your version of
+Armada with the version of this documentation.
+
+The sample configuration can also be viewed in `file form <../_static/armada.conf.sample>`_.
+
+.. literalinclude:: ../_static/armada.conf.sample

docs/source/operations/samplepolicy.rst

@@ -0,0 +1,25 @@
+..
+    Copyright 2017 AT&T Intellectual Property.  All other 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.
+
+Sample Policy File
+==================
+The following is a sample Armada policy file for adaptation and use. It is
+auto-generated from Armada when this documentation is built, so
+if you are having issues with an option, please compare your version of
+Armada with the version of this documentation.
+
+The sample policy file can also be viewed in `file form <../_static/armada.policy.yaml.sample>`_.
+
+.. literalinclude:: ../_static/armada.policy.yaml.sample

setup.cfg

@@ -32,6 +32,10 @@ packages =
 source-dir = docs/source
 build-dir = docs/build
 all_files = 1
+warning-is-error = 1
+
+[upload_sphinx]
+upload-dir = doc/build/html
 
 [entry_points]
 console_scripts =

test-requirements.txt

@@ -2,7 +2,8 @@
 tox
 
 # Docs
-Sphinx
+sphinx>=1.6.2
+sphinx_rtd_theme==0.2.4
 
 # Testing
 flake8==3.3.0