docs(markdown): migrate docs from rst to md (#422)

Migrated docs from `readthedocs.io` to `github.io`. --------- Co-authored-by: Artem Rys <[email protected]>
splunk · May 21, 2024 · 39ccda1 · 39ccda1
1 parent c70b4bf
commit 39ccda1
Show file tree

Hide file tree

Showing 90 changed files with 665 additions and 1,473 deletions.
diff --git a/.github/workflows/docs.yml b/.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
diff --git a/.gitignore b/.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/

diff --git a/.readthedocs.yml b/.readthedocs.yml
diff --git a/README.md b/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).
diff --git a/docs/Makefile b/docs/Makefile
diff --git a/docs/api_reference.rst b/docs/api_reference.rst
diff --git a/docs/api_reference/backend_confs.md b/docs/api_reference/backend_confs.md
@@ -0,0 +1,3 @@
+# backend_confs
+
+::: pytest_splunk_addon_ui_smartx.backend_confs
diff --git a/docs/api_reference/base_test.md b/docs/api_reference/base_test.md
@@ -0,0 +1,3 @@
+# base_test
+
+::: pytest_splunk_addon_ui_smartx.base_test
diff --git a/docs/api_reference/components/base_component.md b/docs/api_reference/components/base_component.md
@@ -0,0 +1,3 @@
+# base_component
+
+::: pytest_splunk_addon_ui_smartx.components.base_component
diff --git a/docs/api_reference/components/conf_table.md b/docs/api_reference/components/conf_table.md
@@ -0,0 +1,3 @@
+# conf_table
+
+::: pytest_splunk_addon_ui_smartx.components.conf_table
diff --git a/docs/api_reference/components/controls/base_control.md b/docs/api_reference/components/controls/base_control.md
@@ -0,0 +1,3 @@
+# base_control
+
+::: pytest_splunk_addon_ui_smartx.components.controls.base_control
diff --git a/docs/api_reference/components/controls/button.md b/docs/api_reference/components/controls/button.md
@@ -0,0 +1,3 @@
+# button
+
+::: pytest_splunk_addon_ui_smartx.components.controls.button
diff --git a/docs/api_reference/components/controls/checkbox.md b/docs/api_reference/components/controls/checkbox.md
@@ -0,0 +1,3 @@
+# checkbox
+
+::: pytest_splunk_addon_ui_smartx.components.controls.checkbox
diff --git a/docs/api_reference/components/controls/index.md b/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)
diff --git a/docs/api_reference/components/controls/learn_more.md b/docs/api_reference/components/controls/learn_more.md
@@ -0,0 +1,3 @@
+# learn_more
+
+::: pytest_splunk_addon_ui_smartx.components.controls.learn_more
diff --git a/docs/api_reference/components/controls/message.md b/docs/api_reference/components/controls/message.md
@@ -0,0 +1,3 @@
+# message
+
+::: pytest_splunk_addon_ui_smartx.components.controls.message
diff --git a/docs/api_reference/components/controls/multi_select.md b/docs/api_reference/components/controls/multi_select.md
@@ -0,0 +1,3 @@
+# multi_select
+
+::: pytest_splunk_addon_ui_smartx.components.controls.multi_select
diff --git a/docs/api_reference/components/controls/oauth_select.md b/docs/api_reference/components/controls/oauth_select.md
@@ -0,0 +1,3 @@
+# oauth_select
+
+::: pytest_splunk_addon_ui_smartx.components.controls.oauth_select
diff --git a/docs/api_reference/components/controls/single_select.md b/docs/api_reference/components/controls/single_select.md
@@ -0,0 +1,3 @@
+# single_select
+
+::: pytest_splunk_addon_ui_smartx.components.controls.single_select
diff --git a/docs/api_reference/components/controls/textbox.md b/docs/api_reference/components/controls/textbox.md
@@ -0,0 +1,3 @@
+# textbox
+
+::: pytest_splunk_addon_ui_smartx.components.controls.textbox
diff --git a/docs/api_reference/components/controls/toggle.md b/docs/api_reference/components/controls/toggle.md
@@ -0,0 +1,3 @@
+# toggle
+
+::: pytest_splunk_addon_ui_smartx.components.controls.toggle
diff --git a/docs/api_reference/components/dropdown.md b/docs/api_reference/components/dropdown.md
@@ -0,0 +1,3 @@
+# dropdown
+
+::: pytest_splunk_addon_ui_smartx.components.dropdown
diff --git a/docs/api_reference/components/entity.md b/docs/api_reference/components/entity.md
@@ -0,0 +1,3 @@
+# entity
+
+::: pytest_splunk_addon_ui_smartx.components.entity
diff --git a/docs/api_reference/components/index.md b/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)
diff --git a/docs/api_reference/components/input_table.md b/docs/api_reference/components/input_table.md
@@ -0,0 +1,3 @@
+# input_table
+
+::: pytest_splunk_addon_ui_smartx.components.input_table
diff --git a/docs/api_reference/components/login.md b/docs/api_reference/components/login.md
@@ -0,0 +1,3 @@
+# login
+
+::: pytest_splunk_addon_ui_smartx.components.login
diff --git a/docs/api_reference/components/table.md b/docs/api_reference/components/table.md
@@ -0,0 +1,3 @@
+# table
+
+::: pytest_splunk_addon_ui_smartx.components.table
diff --git a/docs/api_reference/components/tabs.md b/docs/api_reference/components/tabs.md
@@ -0,0 +1,3 @@
+# tabs
+
+::: pytest_splunk_addon_ui_smartx.components.tabs
diff --git a/docs/api_reference/index.md b/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)
diff --git a/docs/api_reference/pages/index.md b/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)
diff --git a/docs/api_reference/pages/logging.md b/docs/api_reference/pages/logging.md
@@ -0,0 +1,3 @@
+# logging
+
+::: pytest_splunk_addon_ui_smartx.pages.logging
diff --git a/docs/api_reference/pages/login.md b/docs/api_reference/pages/login.md
@@ -0,0 +1,3 @@
+# login
+
+::: pytest_splunk_addon_ui_smartx.pages.login
diff --git a/docs/api_reference/pages/page.md b/docs/api_reference/pages/page.md
@@ -0,0 +1,3 @@
+# page
+
+::: pytest_splunk_addon_ui_smartx.pages.page
diff --git a/docs/api_reference/pages/proxy.md b/docs/api_reference/pages/proxy.md
@@ -0,0 +1,3 @@
+# proxy
+
+::: pytest_splunk_addon_ui_smartx.pages.proxy
diff --git a/docs/api_reference/plugin.md b/docs/api_reference/plugin.md
@@ -0,0 +1,3 @@
+# plugin
+
+::: pytest_splunk_addon_ui_smartx.plugin
diff --git a/docs/api_reference/utils.md b/docs/api_reference/utils.md
@@ -0,0 +1,3 @@
+# utils
+
+::: pytest_splunk_addon_ui_smartx.utils
diff --git a/docs/backend_confs.rst b/docs/backend_confs.rst
diff --git a/docs/base_test.rst b/docs/base_test.rst
diff --git a/docs/components/base_component.rst b/docs/components/base_component.rst
diff --git a/docs/components/conf_table.rst b/docs/components/conf_table.rst
diff --git a/docs/components/controls/base_control.rst b/docs/components/controls/base_control.rst