docs: initial docs

.github/workflows/docs.yml

@@ -0,0 +1,15 @@
+name: docs
+on:
+  push:
+    branches:
+      - main
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-python@v2
+        with:
+          python-version: 3.7
+      - run: pip install mkdocs mkdocs-material
+      - run: mkdocs gh-deploy --force

.gitignore

@@ -32,4 +32,5 @@ output
 # splunk_add_on_ucc_framework/package/default/data/ui/views/redirect.xml
 # splunk_add_on_ucc_framework/uccrestbuilder/builder.py
 .gitmodules
-.pytest_cache/**
+.pytest_cache/**
+site/

.licenserc.yaml

@@ -23,7 +23,6 @@ header:
     - ".github/"
     - ".vscode/"
     - "dist"
-    - "licenses"
     - "**/*.md"
     - "LICENSE"
     - "NOTICE"
@@ -33,6 +32,8 @@ header:
     - "splunk_add_on_ucc_framework/arf_dir_templates/modular_alert_package.settings"
     - "splunk_add_on_ucc_framework/modular_alert_builder/build_core/arf_template/**"
     - "tests/**"
+    - "README.md"
+    - "mkdocs.yml"
     - ".*"
 
   comment: on-failure

README.md

@@ -1,87 +1,17 @@
-# SPDX-FileCopyrightText: 2020 Splunk Inc.
-
 # splunk-add-on-ucc-framework
 
 ![PyPI](https://img.shields.io/pypi/v/splunk-add-on-ucc-framework)
 ![Python](https://img.shields.io/pypi/pyversions/splunk-add-on-ucc-framework.svg)
 
-A framework to generate UI based Splunk Add-ons. It includes UI, Rest handler, Modular input, Oauth, Alert action templates.
-
-> Note: after UCC 5.2 Python 2 specific libraries are not supported anymore.
-> This means if the add-on has `package/lib/py2/requirements.txt` they will 
-> not be installed while running `ucc-gen` command. Therefore modular inputs 
-> that are supposed to run on Python 2 will not be supported by UCC. 
-
-Available as a Github action here: https://github.com/splunk/addonfactory-ucc-generator-action
-
 ## 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.
 
+## Usage
 
-## Features
-
-- Generate UCC based addons for your Splunk Technology Add-ons
-
-## UCC 5
-
-UCC 5 has potentially breaking changes to add-ons using hook extension in the UX. Previously such hooks were limited to un-optimized js files placed in the package.
-Add-ons may now package such extensions with webpack.
-
-## Requirements
-
-- Addon package and globalConfig.json file
-
-> Note: You may refer the globalConfig.json file [here](https://github.com/splunk/addonfactory-ucc-generator/blob/main/tests/data/package_global_config_configuration/globalConfig.json)
-
-
-## Installation
-
-"splunk-add-on-ucc-framework" can be installed via `pip` from `PyPI`:
-
-```bash
-$ pip3 install splunk-add-on-ucc-framework
-```
+For full usage instructions, please visit the Splunk Connect for Syslog [documentation](https://splunk.github.io/addonfactory-ucc-generator/).
 
 ## pre-commit
 
 Please visit `pre-commit` quick start [section](https://pre-commit.com/#quick-start).
-
-## How to use
-
-To build the UCC based addon follow the below steps:
-
-1. Install the `splunk-add-on-ucc-framework` via `pip3`.
-2. Run the `ucc-gen` command.
-3. Make sure that `package` folder and `globalConfig.json` file are present in the addon folder.
-4. The final addon package will be generated, in the `output` folder.
-
-
-## Workflow
-
-By the running the `ucc-gen` command, the following steps are executed:
-1. Cleaning out the `output` folder.
-2. Retrieve the package ID of addon.
-3. Copy UCC template directory under `output/<package_ID>` directory.
-4. Copy `globalConfig.json` file to `output/<package_ID>/appserver/static/js/build` directory.
-5. Collect and install Addon's requirements into `output/<package_ID>/lib` directory of addon's package.
-6. For the addon's requirements, packages are installed according to following table:
-
-    | File Name            | Description                         | Output directory in UCC build |
-    |----------------------|-------------------------------------|-------------------------------|
-    | lib/requirements.txt     | Python3 compatible packages | output/<package_ID>/lib   |
-
-7. Replace tokens in views.
-8. Copy addon's `package/*` to `output/<package_ID>/*` directory.
-9. If an addon requires some additional configurations in packaging than implement the steps in additional_packaging.py
-
-## Params
-
-splunk-add-on-ucc-framework supports the following params:
-
-| Name       | Description                                                                                              |
-|------------|----------------------------------------------------------------------------------------------------------|
-| source     | Folder containing the app.manifest and app source                                                        |
-| config     | Path to the configuration file, Defaults to GlobalConfig.json in the parent directory of source provided |
-| ta-version | Optional override Current version of TA, Default version is version specified in globalConfig.json a Splunkbase compatible version of SEMVER will be used by default                         |

docs/example.rst → docs/example.md

@@ -1,40 +1,30 @@
 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`).
+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, `_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.
+For this you can create a 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 package folder and `app.manifest` inside it.
 
-You also need a :code:`package` folder and :code:`app.manifest` inside it.
+As well as `README.txt` and `LICENSE.txt` files inside package folder. Those
+files may be empty to simplify the showcase of UCC.
 
-.. literalinclude:: example/app.manifest
-   :language: JSON
+To be able to utilise UI features of an add-on you need to create lib
+folder in package folder and create `requirements.txt`.
 
-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.
+Now you are ready to run `ucc-gen` command. If you don't have it
+installed, please refer to installation section.
 
-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
+The structure of the add-on before running `ucc-gen` command should be
 like this:
 
-::
-
     ├── globalConfig.json
     └── package
         ├── LICENSE.txt
@@ -43,19 +33,16 @@ like this:
         └── lib
             └── requirements.txt
 
+Let's assume we want to generate an add-on with version 1.0.0, to
+achieve that we run:
 
-Let's assume we want to generate an add-on with version :code:`1.0.0`, to achieve
-that we run:
+```
+ucc-gen --ta-version=1.0.0
+```
 
-.. 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:
-
-::
+After that, output folder should be created. It should contain
+`Splunk_TA_choose_index` folder. And the structure of
+`Splunk_TA_choose_index` is following:
 
     Splunk_TA_choose_index
     ├── LICENSE.txt
@@ -100,22 +87,22 @@ After that, :code:`output` folder should be created. It should contain
         └── web.conf
 
 Now it's time to package our add-on and install it to Splunk. To install
-:code:`slim` refer to :ref:`steps`.
+slim refer to steps.
 
 To package this particular add-on run:
 
-.. code-block:: console
-
-    slim package output/Splunk_TA_choose_index
+```
+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`.
+After it runs, you should see an archive created in the root folder of
+your add-on. In our case, it should have name:
+`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.
+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.
+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
+![image](images/splunk_add_on_choose_index.png)

docs/how_to_use.md

@@ -0,0 +1,58 @@
+How To Use
+==========
+
+Prerequisites
+-------------
+
+-   `globalConfig.json`
+-   `package` folder
+-   `git` for automatic versioning (when no `ta-version` argument is
+    specified)
+
+Example of globalConfig.json and package folder can be found at
+<https://github.com/splunk/splunk-add-on-for-ucc-example>.
+
+Steps
+-----
+
+-   Install `splunk-add-on-ucc-framework` if it is not installed.
+-   Run the `ucc-gen` command.
+-   The final addon package will be generated, in the `output` folder.
+
+ucc-gen supports the following params:
+
+-   source - [optional] folder containing the `app.manifest` and app
+    source.
+-   config - [optional] path to the configuration file, defaults to
+    `globalConfig.json` in the parent directory of source provided.
+-   ta-version - [optional] override current version of TA, default
+    version is version specified in `globalConfig.json`. Splunkbase
+    compatible version of SEMVER will be used by default.
+
+```
+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
+-----------------
+
+-   Cleans the output folder.
+-   Retrieve the package ID of addon.
+-   Copy UCC template directory under `output/<package_ID>` directory.
+-   Copy globalConfig.json file to
+    `output/<package_ID>/appserver/static/js/build` directory.
+-   Collect and install Addon's requirements into
+    `output/<package_ID>/lib` directory of addon's package.
+-   For the addon's requirements, packages are installed according to
+    following table:
+    -   `lib/requirements.txt` - install Python3 compatible packages into
+        `output/<package_ID>/lib`
+-   Replace tokens in views.
+-   Copy addon's `package/*` to `output/<package_ID>/*` directory.
+-   If an addon requires some additional configurations in packaging
+    than implement the steps in `additional_packaging.py`
+