docs: add UCC usage example

docs/example.rst

@@ -0,0 +1,121 @@
+UCC usage
+=========
+
+Let's assume that you want to create a Splunk add-on with UI to specify Splunk
+index that is going to be used in the add-on. Let's also assume that you do not
+want to show indexes that are for internal use only (like, :code:`_internal`).
+
+For this you can create a :code:`globalConfig.json` file and specify that you
+want one configuration tab called "Global Settings", one UI component on that
+tab that will handle index management and store selected index in specific
+add-on configuration file.
+
+.. literalinclude:: example/globalConfig.json
+   :language: JSON
+
+You also need a :code:`package` folder and :code:`app.manifest` inside it.
+
+.. literalinclude:: example/app.manifest
+   :language: JSON
+
+As well as :code:`README.txt` and :code:`LICENSE.txt` files inside
+:code:`package` folder. Those files may be empty to simplify the showcase of UCC.
+
+To be able to utilise UI features of an add-on you need to create :code:`lib`
+folder in :code:`package` folder and create :code:`requirements.txt`.
+
+.. literalinclude:: example/requirements.txt
+   :language: text
+
+Now you are ready to run :code:`ucc-gen` command. If you don't have it installed,
+please refer to :ref:`installation` section.
+
+The structure of the add-on before running :code:`ucc-gen` command should be
+like this:
+
+::
+
+    ├── globalConfig.json
+    └── package
+        ├── LICENSE.txt
+        ├── README.txt
+        ├── app.manifest
+        └── lib
+            └── requirements.txt
+
+
+Let's assume we want to generate an add-on with version :code:`1.0.0`, to achieve
+that we run:
+
+.. code-block:: console
+
+    ucc-gen --ta-version=1.0.0
+
+After that, :code:`output` folder should be created. It should contain
+:code:`Splunk_TA_choose_index` folder. And the structure of
+:code:`Splunk_TA_choose_index` is following:
+
+::
+
+    Splunk_TA_choose_index
+    ├── LICENSE.txt
+    ├── README
+    │   └── splunk_ta_choose_index_settings.conf.spec
+    ├── README.txt
+    ├── VERSION
+    ├── app.manifest
+    ├── appserver
+    │   ├── static
+    │   │   └── js
+    │   │       └── build
+    │   │           ├── 0.js
+    │   │           ├── 0.licenses.txt
+    │   │           ├── 1.js
+    │   │           ├── 1.licenses.txt
+    │   │           ├── 3.js
+    │   │           ├── 3.licenses.txt
+    │   │           ├── 4.js
+    │   │           ├── 4.licenses.txt
+    │   │           ├── entry_page.js
+    │   │           ├── entry_page.licenses.txt
+    │   │           └── globalConfig.json
+    │   └── templates
+    │       └── base.html
+    ├── bin
+    │   ├── Splunk_TA_choose_index_rh_settings.py
+    │   └── import_declare_test.py
+    ├── lib
+    │   ├── <libraries>
+    │   └── ...
+    └── default
+        ├── app.conf
+        ├── data
+        │   └── ui
+        │       ├── nav
+        │       │   └── default.xml
+        │       └── views
+        │           └── configuration.xml
+        ├── restmap.conf
+        ├── splunk_ta_choose_index_settings.conf
+        └── web.conf
+
+Now it's time to package our add-on and install it to Splunk. To install
+:code:`slim` refer to :ref:`steps`.
+
+To package this particular add-on run:
+
+.. code-block:: console
+
+    slim package output/Splunk_TA_choose_index
+
+After it runs, you should see an archive created in the root folder of your
+add-on. In our case, it should have name:
+:code:`Splunk_TA_choose_index-1.0.0.tar.gz`.
+
+This is an archive that can be loaded into Splunk through
+"Apps > Manage Apps > Install app from file" interface.
+
+Once you load it and restart Splunk, you can go to
+"Apps > Splunk Add-on to choose index" and see interface like this one.
+
+.. image:: images/splunk_add_on_choose_index.png

docs/example/app.manifest

@@ -0,0 +1,51 @@
+{
+    "dependencies": null,
+    "incompatibleApps": null,
+    "info": {
+        "author": [
+            {
+                "company": null,
+                "email": null,
+                "name": ""
+            }
+        ],
+        "classification": {
+            "categories": [],
+            "developmentStatus": null,
+            "intendedAudience": null
+        },
+        "commonInformationModels": null,
+        "description": "Splunk Add-on to choose index",
+        "id": {
+            "group": null,
+            "name": "Splunk_TA_choose_index",
+            "version": "1.0.0"
+        },
+        "license": {
+            "name": null,
+            "text": "./LICENSE.txt",
+            "uri": null
+        },
+        "privacyPolicy": {
+            "name": null,
+            "text": null,
+            "uri": null
+        },
+        "releaseDate": null,
+        "releaseNotes": {
+            "name": null,
+            "text": "./README.txt",
+            "uri": null
+        },
+        "title": "Splunk Add-on to choose index"
+    },
+    "inputGroups": null,
+    "platformRequirements": null,
+    "schemaVersion": "2.0.0",
+    "supportedDeployments": [
+        "_standalone",
+        "_distributed"
+    ],
+    "targetWorkloads": null,
+    "tasks": null
+}

docs/example/globalConfig.json

@@ -0,0 +1,44 @@
+{
+    "pages": {
+        "configuration": {
+            "tabs": [
+                {
+                    "name": "global_settings",
+                    "entity": [
+                        {
+                            "type": "singleSelect",
+                            "label": "Index",
+                            "help": "An index is a type of data repository. Select the index in which you want to collect the events.",
+                            "defaultValue": "main",
+                            "required": true,
+                            "validators": [
+                                {
+                                    "type": "string",
+                                    "maxLength": 80,
+                                    "errorMsg": "Maximum length allowed for index is 80",
+                                    "minLength": 1
+                                }
+                            ],
+                            "field": "index",
+                            "options": {
+                                "createSearchChoice": true,
+                                "denyList": "^_.*$",
+                                "endpointUrl": "data/indexes"
+                            }
+                        }
+                    ],
+                    "title": "Global settings"
+                }
+            ],
+            "title": "Configuration",
+            "description": "Set up your add-on"
+        }
+    },
+    "meta": {
+        "name": "Splunk_TA_choose_index",
+        "restRoot": "Splunk_TA_choose_index",
+        "version": "1.0.0",
+        "displayName": "Splunk_TA_choose_index",
+        "schemaVersion": "0.0.3"
+    }
+}

docs/example/requirements.txt

@@ -0,0 +1 @@
+splunktaucclib

docs/how_to_use.rst

@@ -10,11 +10,13 @@ Prerequisites
 
 Example of :code:`globalConfig.json` and :code:`package` folder can be found at https://github.com/splunk/splunk-add-on-for-ucc-example.
 
+.. _steps:
+
 Steps
 -----
 
 * Install :code:`splunk-add-on-ucc-framework` if it is not installed.
-* Run the :code:`ucc-gen`. command.
+* Run the :code:`ucc-gen` command.
 * The final addon package will be generated, in the :code:`output` folder.
 
 :code:`ucc-gen` supports the following params:
@@ -23,6 +25,13 @@ Steps
 * :code:`config` - [optional] path to the configuration file, defaults to :code:`globalConfig.json` in the parent directory of source provided.
 * :code:`ta-version` - [optional] override current version of TA, default version is version specified in :code:`globalConfig.json`. Splunkbase compatible version of SEMVER will be used by default.
 
+.. code-block:: console
+
+    pip install splunk-packaging-toolkit
+    slim package output/<package_ID>
+
+After completing the packaging slim should also output path to the package for distribution.
+
 What ucc-gen does
 -----------------
 
@@ -37,4 +46,4 @@ What ucc-gen does
 
 * Replace tokens in views.
 * Copy addon's :code:`package/*` to :code:`output/<package_ID>/*` directory.
-* If an addon requires some additional configurations in packaging than implement the steps in additional_packaging.py
+* If an addon requires some additional configurations in packaging than implement the steps in :code:`additional_packaging.py`

docs/index.rst

@@ -12,6 +12,7 @@ Welcome to addonfactory-ucc-generator's documentation!
 
    overview
    how_to_use
+   example
    troubleshooting
 
 

docs/overview.rst

@@ -12,14 +12,16 @@ It includes UI, Rest handler, Modular input, Oauth, Alert action templates.
 What is UCC?
 ------------
 UCC stands for Universal Configuration Console.
-It is a service for generating Splunk Add-ons which is easily customizable and flexible.
-UCC provides basic UI template for creating Addon's UI.
-It is helpful to control the activity by using hooks and other functionalities.
+The purpose of having a framework for add-on generation is to simplify the
+process of add-on creation for the developers.
+UCC 5.X uses SplunkUI which is a new UI framework based on React.
 
 Features
 --------
 * Generate UCC based addons for your Splunk Technology Add-ons
 
+.. _installation:
+
 Installation
 ------------
 splunk-add-on-ucc-framework can be installed via pip from PyPI: