docs(markdown): migrate docs from rst to md

.github/workflows/docs.yml

@@ -0,0 +1,29 @@
+name: docs
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pages: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.8
+      - run: |
+          curl -sSL https://install.python-poetry.org | python3 - --version 1.5.1
+          pip install mkdocs mkdocs-material mkdocstrings-python
+      - name: Deploy to GitHub Pages
+        if: github.ref_name == 'main'
+        run: mkdocs gh-deploy --force --strict
+      - name: Build Docs
+        if: github.ref_name != 'main'
+        run: mkdocs build --strict

.gitignore

@@ -101,9 +101,9 @@ celerybeat.pid
 
 # Environments
 .env
-.venv
+# ignore all venv with different Py versions
+.venv*
 env/
-venv/
 ENV/
 env.bak/
 venv.bak/

README.md

@@ -1,77 +1,12 @@
-# SmartX
+# addon-factory-smartx-ui-test-library
 
-UCC based Add-on UI automation framework 
+![PyPI](https://img.shields.io/pypi/v/pytest-splunk-addon-ui-smartx)
+![Python](https://img.shields.io/pypi/pyversions/pytest-splunk-addon-ui-smartx.svg)
 
-Confluence Page link: https://confluence.splunk.com/display/PROD/SmartX+UI+Automation+Framework+for+Ucc+based+Add-ons
+## What is SmartX UI Test Framework
 
-ReadTheDocs Page link: https://addon-factory-smartx-ui-test-library.readthedocs.io
+This framework is wrapper on selenium to write UI test cases for Splunk Add-ons.
 
-## Table of contents
+## Usage
 
-- [Goal](#goal)
-- [Design](#design)
-- [Features](#features)
-- [Build test cases using the framework](#build-test-cases-using-the-framework)
-- [Steps to test in Local environment](#steps-to-test-in-local-environment)
-- [Steps to test with Saucelabs](#steps-to-test-with-saucelabs)
-
-### Goal
-
-To test all the UI configuration page of the Splunk add-ons. All the add-ons are built with the same template. The configuration pages consist of an Input page and a configuration page that has different tabs to configure logging, proxy settings and add product account in the add-ons. To support the testing of all the add-ons, a generic framework should be made, which can be used in the test cases for all the add-ons. The framework should have methods that can interact with UI components and test the working of UI.
-
-### Design
-
-For UI development, we follow a practice in which we create a set of components first. The component has its own state-cycle. The component will be reusable so that it can be placed on any page. A web-page will be a composition of these components placed in the proper container.
-
-The testing framework will follow the same practice. It will have classes for all the components used in all the pages. These “Component” class will consist of methods to interact with the component, to get & set values in the component.  These components will be put on different pages. The structure is created so that it can easily be maintained and understandable. As per design, the class “Page” should only be used to contain a set of components. No interaction methods should be in the Page class.
-
-    The structure of the framework can be divided into 3 parts.
-
-    Components   : A UI component with which a user interacts with.
-    Pages        : Holds multiple components of a specific page
-    Test cases   : Tests the interaction & values in the components
-
-### Features
-
-- pytest fixture to control when the browser should be initialized & tear-downed.
-- Flag to easily convert the environment from SauceLabs to local for debugging purposes.
-- Screenshot when any test case fails.
-- An Html report containing the trace-back and the screenshots of the failed test cases.
-- Being able to read environment variables to dynamically change the URL and the credentials of a test page.
-- Backend configuration that can be fetched from the management API of the Splunk instance.
-- Reruns, the test cases will be rerunning to avoid some rare timeout/network issues
-
-
-### Build test cases using the framework
-
-1. Create the appropriate folders and pytest files within the TA's test/ui directory
-2. Create Add-on specific Page classes (we only need to specify which components it contains, demo: server_page)
-3. Implement the test-cases by using the page classes & its components
-4. Jenkins integrations
-
-Demo link : https://git.splunk.com/projects/SOLN/repos/ta-microsoft-scom/browse/test/ui
-
-### Steps to test in Local environment
-
-1. Install SmartX by using 'pip install pytest-splunk-addon-ui-smartx' or cloning this repository and running 'poetry install'
-2. Download Browser's specific driver
-    For Chrome: download chromedriver
-    For Firefox: download geckodriver
-    For IE: download IEdriverserver
-3. Put the downloaded driver into test/ui/ directory, make sure that it is within the environment's PATH variable, and that it is executable
-4. For Internet explorer, The steps mentioned at below link must be performed:
-https://github.com/SeleniumHQ/selenium/wiki/InternetExplorerDriver#required-configuration
-5. Execute the test cases:
- ```script
-  pytest -vv --browser={browser} --local --splunk-host={web_url} --splunk-port={mgmt_url} --splunk-user {username} --splunk-password {password}
- ```
-### Steps to test with Saucelabs
-
-1. Install SmartX by using 'pip install pytest-splunk-addon-ui-smartx' or cloning this repository and running 'poetry install'
-2. Configure saucelabs credentials as environment variables
-    SAUCE_USERNAME : <saucelabs_username>
-    SAUCE_PASSWORD : <saucelabs_access_key>
-3. Execute the test case
-```script
-pytest -vv --browser={browser} --splunk-host={web_url} --splunk-port={mgmt_url} --setup-retry-count={retry-count} --splunk-user {username} --splunk-password {password}
-```
+For full usage instructions, please visit the [documentation](https://splunk.github.io/addon-factory-smartx-ui-test-library).

docs/api_reference/backend_confs.md

@@ -0,0 +1,3 @@
+# backend_confs
+
+::: pytest_splunk_addon_ui_smartx.backend_confs

docs/api_reference/base_test.md

@@ -0,0 +1,3 @@
+# base_test
+
+::: pytest_splunk_addon_ui_smartx.base_test

docs/api_reference/components/base_component.md

@@ -0,0 +1,3 @@
+# base_component
+
+::: pytest_splunk_addon_ui_smartx.components.base_component

docs/api_reference/components/conf_table.md

@@ -0,0 +1,3 @@
+# conf_table
+
+::: pytest_splunk_addon_ui_smartx.components.conf_table

docs/api_reference/components/controls/base_control.md

@@ -0,0 +1,3 @@
+# base_control
+
+::: pytest_splunk_addon_ui_smartx.components.controls.base_control

docs/api_reference/components/controls/button.md

@@ -0,0 +1,3 @@
+# button
+
+::: pytest_splunk_addon_ui_smartx.components.controls.button

docs/api_reference/components/controls/checkbox.md

@@ -0,0 +1,3 @@
+# checkbox
+
+::: pytest_splunk_addon_ui_smartx.components.controls.checkbox

docs/api_reference/components/controls/index.md

@@ -0,0 +1,14 @@
+# controls
+
+The following is the API Reference for SmartX Controls:
+
++ [base_control](base_control.md)
++ [button](button.md)
++ [checkbox](checkbox.md)
++ [learn_more](learn_more.md)
++ [message](message.md)
++ [multi_select](multi_select.md)
++ [oauth_select](oauth_select.md)
++ [single_select](single_select.md)
++ [textbox](textbox.md)
++ [toggle](toggle.md)

docs/api_reference/components/controls/learn_more.md

@@ -0,0 +1,3 @@
+# learn_more
+
+::: pytest_splunk_addon_ui_smartx.components.controls.learn_more

docs/api_reference/components/controls/message.md

@@ -0,0 +1,3 @@
+# message
+
+::: pytest_splunk_addon_ui_smartx.components.controls.message

docs/api_reference/components/controls/multi_select.md

@@ -0,0 +1,3 @@
+# multi_select
+
+::: pytest_splunk_addon_ui_smartx.components.controls.multi_select

docs/api_reference/components/controls/oauth_select.md

@@ -0,0 +1,3 @@
+# oauth_select
+
+::: pytest_splunk_addon_ui_smartx.components.controls.oauth_select

docs/api_reference/components/controls/single_select.md

@@ -0,0 +1,3 @@
+# single_select
+
+::: pytest_splunk_addon_ui_smartx.components.controls.single_select

docs/api_reference/components/controls/textbox.md

@@ -0,0 +1,3 @@
+# textbox
+
+::: pytest_splunk_addon_ui_smartx.components.controls.textbox

docs/api_reference/components/controls/toggle.md

@@ -0,0 +1,3 @@
+# toggle
+
+::: pytest_splunk_addon_ui_smartx.components.controls.toggle

docs/api_reference/components/dropdown.md

@@ -0,0 +1,3 @@
+# dropdown
+
+::: pytest_splunk_addon_ui_smartx.components.dropdown

docs/api_reference/components/entity.md

@@ -0,0 +1,3 @@
+# entity
+
+::: pytest_splunk_addon_ui_smartx.components.entity

docs/api_reference/components/index.md

@@ -0,0 +1,12 @@
+# components
+
+The following is the API Reference for SmartX Components:
+
++ [base_component](base_component.md)
++ [conf_table](conf_table.md)
++ [dropdown](dropdown.md)
++ [entity](entity.md)
++ [input_table](input_table.md)
++ [login](login.md)
++ [table](table.md)
++ [tabs](tabs.md)

docs/api_reference/components/input_table.md

@@ -0,0 +1,3 @@
+# input_table
+
+::: pytest_splunk_addon_ui_smartx.components.input_table

docs/api_reference/components/login.md

@@ -0,0 +1,3 @@
+# login
+
+::: pytest_splunk_addon_ui_smartx.components.login

docs/api_reference/components/table.md

@@ -0,0 +1,3 @@
+# table
+
+::: pytest_splunk_addon_ui_smartx.components.table

docs/api_reference/components/tabs.md

@@ -0,0 +1,3 @@
+# tabs
+
+::: pytest_splunk_addon_ui_smartx.components.tabs

docs/api_reference/index.md

@@ -0,0 +1,31 @@
+The following is the API Reference for SmartX:
+
+- [backend_conf](backend_confs.md)
+- [base_test](base_test.md)
+- [plugin](plugin.md)
+- [utils](utils.md)
+- [pages](pages/index.md)
+    + [logging](pages/logging.md)
+    + [login](pages/login.md)
+    + [page](pages/page.md)
+    + [proxy](pages/proxy.md)
+- [components](components/index.md)
+    + [base_component](components/base_component.md)
+    + [conf_table](components/conf_table.md)
+    + [dropdown](components/dropdown.md)
+    + [entity](components/entity.md)
+    + [input_table](components/input_table.md)
+    + [login](components/login.md)
+    + [table](components/table.md)
+    + [tabs](components/tabs.md)
+- [controls](components/controls/index.md)
+    + [base_control](components/controls/base_control.md)
+    + [button](components/controls/button.md)
+    + [checkbox](components/controls/checkbox.md)
+    + [learn_more](components/controls/learn_more.md)
+    + [message](components/controls/message.md)
+    + [multi_select](components/controls/multi_select.md)
+    + [oauth_select](components/controls/oauth_select.md)
+    + [single_select](components/controls/single_select.md)
+    + [textbox](components/controls/textbox.md)
+    + [toggle](components/controls/toggle.md)

docs/api_reference/pages/index.md

@@ -0,0 +1,8 @@
+# pages
+
+The following is the API Reference for SmartX Pages:
+
++ [logging](logging.md)
++ [login](login.md)
++ [page](page.md)
++ [proxy](proxy.md)

docs/api_reference/pages/logging.md

@@ -0,0 +1,3 @@
+# logging
+
+::: pytest_splunk_addon_ui_smartx.pages.logging

docs/api_reference/pages/login.md

@@ -0,0 +1,3 @@
+# login
+
+::: pytest_splunk_addon_ui_smartx.pages.login

docs/api_reference/pages/page.md

@@ -0,0 +1,3 @@
+# page
+
+::: pytest_splunk_addon_ui_smartx.pages.page

docs/api_reference/pages/proxy.md

@@ -0,0 +1,3 @@
+# proxy
+
+::: pytest_splunk_addon_ui_smartx.pages.proxy

docs/api_reference/plugin.md

@@ -0,0 +1,3 @@
+# plugin
+
+::: pytest_splunk_addon_ui_smartx.plugin

docs/api_reference/utils.md

@@ -0,0 +1,3 @@
+# utils
+
+::: pytest_splunk_addon_ui_smartx.utils