diff --git a/.gitignore b/.gitignore index c0b1629c..5872473c 100644 --- a/.gitignore +++ b/.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 - diff --git a/README.rst b/README.rst index e49ec8ed..16276580 100644 --- a/README.rst +++ b/README.rst @@ -12,7 +12,7 @@ Roadmap Detailed roadmap can be viewed `here `_ -Issues can be reported `here `_ +Issues can be reported `on GitHub `_ Installation ------------ @@ -26,7 +26,7 @@ Using armada `docs `_ Getting Started --------------- -Get started guide can be found in our `docs `_ +Get started guide can be found in our `Getting Started docs `_ Usage ----- diff --git a/docs/source/_static/.placeholder b/docs/source/_static/.placeholder new file mode 100644 index 00000000..e69de29b diff --git a/docs/source/conf.py b/docs/source/conf.py index e8d0e72f..65dc4f42 100644 --- a/docs/source/conf.py +++ b/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'), ] diff --git a/docs/source/development/contributing.rst b/docs/source/development/contributing.rst new file mode 100644 index 00000000..b1cd2f37 --- /dev/null +++ b/docs/source/development/contributing.rst @@ -0,0 +1 @@ +.. include:: ../../../CONTRIBUTING.rst diff --git a/docs/source/development/index.rst b/docs/source/development/index.rst index 1c34ff69..0c7c2b65 100644 --- a/docs/source/development/index.rst +++ b/docs/source/development/index.rst @@ -11,4 +11,4 @@ Developers Guide :caption: Contents: getting-started.rst - ../../../CONTRIBUTING.rst + contributing.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index 9400ba78..18a9fd4f 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -15,8 +15,6 @@ Welcome to Armada's documentation! operations/index commands/index - - Indices and tables ================== diff --git a/docs/source/operations/guide-api.rst b/docs/source/operations/guide-api.rst index 83e1c266..db27fd6f 100644 --- a/docs/source/operations/guide-api.rst +++ b/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: diff --git a/docs/source/operations/guide-build-armada-yaml.rst b/docs/source/operations/guide-build-armada-yaml.rst index 9a636338..634cd6c2 100644 --- a/docs/source/operations/guide-build-armada-yaml.rst +++ b/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 -~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^ :: diff --git a/docs/source/operations/guide-exceptions.rst b/docs/source/operations/guide-exceptions.rst index 9f592e7e..27cdb38e 100644 --- a/docs/source/operations/guide-exceptions.rst +++ b/docs/source/operations/guide-exceptions.rst @@ -52,7 +52,7 @@ Chartbuilder Exceptions +-----------------------------+-------------------------------------------------------------+ Source Exceptions -=============== +================= +--------------------------+---------------------------------------------------------------------+ | Exception | Error Description | diff --git a/docs/source/operations/guide-helm-plugin.rst b/docs/source/operations/guide-helm-plugin.rst index b5a65a16..0d6ede82 100644 --- a/docs/source/operations/guide-helm-plugin.rst +++ b/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. diff --git a/docs/source/operations/guide-troubleshooting.rst b/docs/source/operations/guide-troubleshooting.rst index f852c2dd..6df3a3bb 100644 --- a/docs/source/operations/guide-troubleshooting.rst +++ b/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 `_. If the issue does -not exist, please create an issue. +issues `section `_. If the issue does +not exist, please create an issue. diff --git a/docs/source/operations/guide-use-armada.rst b/docs/source/operations/guide-use-armada.rst index 964a6a5a..75d6e2ce 100644 --- a/docs/source/operations/guide-use-armada.rst +++ b/docs/source/operations/guide-use-armada.rst @@ -6,9 +6,9 @@ Prerequisites Kubernetes Cluster -Tiller Service `here `_ +`Tiller Service `_ -Armada.yaml `here `_ +`Armada.yaml `_ .. note:: diff --git a/docs/source/operations/index.rst b/docs/source/operations/index.rst index f40233ee..beecde49 100644 --- a/docs/source/operations/index.rst +++ b/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 diff --git a/docs/source/operations/sampleconf.rst b/docs/source/operations/sampleconf.rst new file mode 100644 index 00000000..9e2ec4f6 --- /dev/null +++ b/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 diff --git a/docs/source/operations/samplepolicy.rst b/docs/source/operations/samplepolicy.rst new file mode 100644 index 00000000..d49873d3 --- /dev/null +++ b/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 diff --git a/setup.cfg b/setup.cfg index 788851a8..653ebfe3 100644 --- a/setup.cfg +++ b/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 = diff --git a/test-requirements.txt b/test-requirements.txt index 358d094b..af6db1d7 100644 --- a/test-requirements.txt +++ b/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