docs: update api reference documentation (#891)

This PR updates API reference documentation as below
-  add missing function implementation and its params.
-  correcting parameters doc for some functions
-  add documentation for cim-compliance-report

Ref: https://splunk.atlassian.net/browse/ADDON-75003

Author: dvarasani-crest

docs/api_reference/cim_compliance_report.md

@@ -0,0 +1,21 @@
+# CimComplianceReport
+
+::: pytest_splunk_addon.cim_compliance
+    handler: python
+
+## CIMReportGenerator
+
+::: pytest_splunk_addon.cim_compliance.cim_report_generator
+    handler: python
+
+
+## MarkDownReport
+
+::: pytest_splunk_addon.cim_compliance.markdown_report
+    handler: python
+
+
+## MarkDownTable
+
+::: pytest_splunk_addon.cim_compliance.markdown_table
+    handler: python

mkdocs.yml

@@ -74,5 +74,6 @@ nav:
       - AppTestGenerator: "api_reference/app_test_generator.md"
       - DataGenerator: "api_reference/sample_generation.md"
       - EventIngestor: "api_reference/event_ingestion.md"
+      - CimComplianceReport: "api_reference/cim_compliance_report.md"
   - Contributing: "contributing.md"
   - Troubleshooting: "troubleshoot.md"

pytest_splunk_addon/addon_parser/fields.py

@@ -28,6 +28,7 @@ class Field(object):
 
     * name (str): name of the field
     * type (str): Field type. Supported [required, conditional, optional]
+    * multi_value (bool): True if field is multi value field
     * expected_values (list): The field should have this expected values
     * negative_values (list): The field should not have negative values
     * condition (spl): The field should only be checked if the condition satisfies

pytest_splunk_addon/addon_parser/props_parser.py

@@ -182,8 +182,8 @@ def _get_extract_fields(self, name: str, value: str):
             EXTRACT-one = regex with (?<capturing_group>.*)
 
         Args:
-            name: key in the configuration settings
-            value: value of the respective name in the configuration
+            name (str): key in the configuration settings
+            value (str): value of the respective name in the configuration
 
         Regex:
             Parse the fields from a regex. Examples,
@@ -220,8 +220,8 @@ def _get_eval_fields(self, name, value):
             EVAL-action = if(isnull(action), "unknown", action)
 
         Args:
-            name: key in the configuration settings
-            value: value of the respective name in the configuration
+            name (str): key in the configuration settings
+            value (str): value of the respective name in the configuration
 
         Yields:
             generator of fields
@@ -240,8 +240,8 @@ def _get_fieldalias_fields(self, name: str, value: str):
             FIELDALIAS-class = source AS dest, sc2 AS dest2
 
         Args:
-            name: key in the configuration settings
-            value: value of the respective name in the configuration
+            name (str): key in the configuration settings
+            value (str): value of the respective name in the configuration
 
         Regex:
             Description:
@@ -274,8 +274,8 @@ def _get_report_fields(self, name: str, value: str):
         transforms.conf and returns the list
 
         Args:
-            name: key in the configuration settings
-            value: value of the respective name in the configuration
+            name (str): key in the configuration settings
+            value (str): value of the respective name in the configuration
 
         Yields:
             generator of (transform_stanza ,fields) parsed from transforms.conf
@@ -294,8 +294,8 @@ def _get_lookup_fields(self, name: str, value: str):
         Extracts the lookup fields
 
         Args:
-            name: key in the configuration settings
-            value: value of the respective name in the configuration
+            name (str): key in the configuration settings
+            value (str): value of the respective name in the configuration
 
         Returns:
             List of lookup fields

pytest_splunk_addon/cim_compliance/cim_report_generator.py

@@ -55,7 +55,7 @@
 
 class CIMReportGenerator(object):
     """
-    Generate the Report
+    Generate the Report.
     data format::
 
         [
@@ -67,6 +67,9 @@ class CIMReportGenerator(object):
                     "status": "pass"/"fail"
                 }
         ]
+
+    Args:
+        data (list): List of dictionaries with specified format.
     """
 
     def __init__(self, data=[], report_class=MarkDownReport):
@@ -78,7 +81,7 @@ def add_data(self, data):
         adds data to object property.
 
         Args:
-            data(list): List of dictionaries with specified format.
+            data (list): List of dictionaries with specified format.
         """
         self.data.append(data)
 
@@ -87,8 +90,8 @@ def _group_by(self, keys, data=None):
         Function to generate group of data using Keys provided
 
         Args:
-            keys(list): Contains keys to group data by.
-            data(list): list of dictionaries with specified format.
+            keys (list): Contains keys to group data by.
+            data (list): list of dictionaries with specified format.
 
         Yields:
             data_set.DataSet: data set object mapped with the tags
@@ -105,8 +108,8 @@ def _get_count_by(self, keys, data=None):
         Function to generate count of data using Keys provided
 
         Args:
-            keys(list): Contains keys to generate count by.
-            data(list): list of dictionaries with specified format.
+            keys (list): Contains keys to generate count by.
+            data (list): list of dictionaries with specified format.
 
         Yields:
             data_set.DataSet: data set object mapped with the tags
@@ -123,7 +126,7 @@ def pass_count(counter):
         Function to Get count in Pass/Total format.
 
         Args:
-            counter(collections.Counter): Contains counts of passing/failing Testcases.
+            counter (collections.Counter): Contains counts of passing/failing Testcases.
 
         Yields:
             String: string with pass/total format.
@@ -139,7 +142,7 @@ def fail_count(counter):
         Function to Get count in Fail/Total format.
 
         Args:
-            counter(collections.Counter): Contains counts of passing/failing Testcases.
+            counter (collections.Counter): Contains counts of passing/failing Testcases.
 
         Yields:
             String: string with fail/total format.
@@ -231,7 +234,9 @@ def generate_field_summary_table(self):
             del field_summary_table
 
     def generate_skip_tests_table(self):
-        """ """
+        """
+        Displays summary of the skipped tests
+        """
         skipped_tests = list(filter(lambda d: d["status"] == "skipped", self.data))
         if skipped_tests:
             skipped_tests_table = MarkdownTable(
@@ -255,7 +260,7 @@ def generate_report(self, report_path):
         Function to generate report from the stored data.
 
         Args:
-            report_path(string): Path to create the report.
+            report_path (string): Path to create the report.
         """
         self.report_generator.set_title("CIM AUDIT REPORT")
         self.data.sort(

pytest_splunk_addon/cim_compliance/markdown_report.py

@@ -20,6 +20,10 @@
 
 
 class MarkDownReport(CIMReport):
+    """
+    Generate the markdown content
+    """
+
     def __init__(self):
         self.markdown_str = ""
         self.note_str = ""
@@ -29,7 +33,7 @@ def set_title(self, title_string):
         Function to set title of a report
 
         Args:
-            title_string(string): String containing title for report.
+            title_string (str): String containing title for report.
         """
         self.title_str = "# {} \n".format(title_string)
 
@@ -38,7 +42,7 @@ def add_section_title(self, section_title):
         Function to add new section to report
 
         Args:
-            section_title(string): String containing title for new Section.
+            section_title (str): String containing title for new Section.
         """
         self.markdown_str += "\n## {}\n".format(section_title)
 
@@ -47,7 +51,7 @@ def add_section_description(self, description):
         Adds description string to the section
 
         Args:
-            description(str): Description string.
+            description (str): Description string.
         """
         self.markdown_str += "\n**Description:** " + description + "\n"
 
@@ -56,7 +60,7 @@ def add_section_note(self, section_note):
         Function to set Note in a report
 
         Args:
-            section_note(string): String containing note for report.
+            section_note (str): String containing note for report.
         """
         self.note_str = "## Note: {} \n".format(section_note)
 
@@ -65,7 +69,7 @@ def add_table(self, table_string):
         Function to add a table to the Report.
 
         Args:
-            table_string(string): Stringified table.
+            table_string (str): Stringified table.
         """
         self.markdown_str += table_string
 
@@ -74,7 +78,7 @@ def write(self, path):
         Function to add a table to the Report.
 
         Args:
-            path(string) : path to store report file.
+            path (str) : path to store report file.
         """
         with open(path, "w") as report:
             report.write(self.title_str)

pytest_splunk_addon/cim_compliance/markdown_table.py

@@ -20,6 +20,14 @@
 
 
 class MarkdownTable(BaseTable):
+    """
+    Generate table in markdown format
+
+    Args:
+        table_title (str): Title of the table
+        header_list (list(str)): List of header names
+    """
+
     def __init__(self, table_title, header_list):
         self.table_title = self.__set_title(table_title)
         self.table_headers = self.__set_headers(header_list)
@@ -32,7 +40,7 @@ def __set_title(self, title):
         Adds Title string to the table
 
         Args:
-            title(str): Title string.
+            title (str): Title string.
         """
         return "### {}".format(title) if title else ""
 
@@ -41,7 +49,7 @@ def __set_headers(self, header_list):
         Sets the header column for the table.
 
         Args:
-            header_list(list): Contains list of column headers.
+            header_list (list): Contains list of column headers.
         """
         header_str = "\n"
         helper_str = ""
@@ -55,7 +63,7 @@ def set_description(self, description):
         Adds description string to the table
 
         Args:
-            description(str): Description string.
+            description (str): Description string.
         """
         self.table_description = "\n {} \n".format(description)
 
@@ -64,7 +72,7 @@ def add_row(self, value_list):
         Expects a list of row values to be added in the table
 
         Args:
-            value_list(list): Contains list of row values
+            value_list (list): Contains list of row values
         """
         row_element = ""
         for each_value in value_list:
@@ -76,7 +84,7 @@ def set_note(self, note_str):
         It adds the note at the end of the table
 
         Args:
-            note_str(str): Note string to be added.
+            note_str (str): Note string to be added.
         """
         self.table_note = "\n*NOTE: {} *\n ".format(note_str)
 

pytest_splunk_addon/cim_compliance/plugin.py

@@ -38,6 +38,9 @@ def pytest_sessionfinish(self, session):
     def pytest_runtest_logreport(self, report):
         """
         Collect the data to be added into the report.
+
+        Args:
+            report (TestReport): test report object
         """
         if report.when == "call" and "test_cim_required_fields" in report.nodeid:
             data_dict = {}

pytest_splunk_addon/cim_tests/data_model.py

@@ -42,8 +42,8 @@ def _get_mapped_datasets(self, addon_tags, data_sets, mapped_datasets=[]):
         If the parent data_set is mapped, check the child data_sets too
 
         Args:
-            addon_tags(list): Contains tags mapped to a stanza
-            data_sets(list): list of data sets to check with
+            addon_tags (list): Contains tags mapped to a stanza
+            data_sets (list): list of data sets to check with
 
         Yields:
             data_set.DataSet: data set object mapped with the tags
@@ -62,7 +62,7 @@ def get_mapped_datasets(self, addon_tags):
         Get all mapped dataSets for an Add-on's tags stanza
 
         Args:
-            addon_tags(list): Contains tags mapped to a stanza
+            addon_tags (list): Contains tags mapped to a stanza
 
         Yields:
             data_set.DataSet: data set object mapped with the tags

pytest_splunk_addon/cim_tests/data_model_handler.py

@@ -79,6 +79,9 @@ def load_data_models(self, data_model_path):
         """
         Parse all the data model JSON files one by one
 
+        Args:
+            data_model_path (str): path to the datamodel schema json file
+
         Yields:
             (cim_tests.data_model.DataModel): parsed data model object
         """

pytest_splunk_addon/cim_tests/data_set.py

@@ -25,7 +25,8 @@ class DataSet(object):
     Handles a single data set
 
     Args:
-        data_set_json(dict): Json of a single DataSet
+        data_set_json (dict): Json of a single DataSet
+        data_model (str): Name of the data model
     """
 
     def __init__(self, data_set_json, data_model):
@@ -55,8 +56,8 @@ def load_dataset(cls, dataset_list, data_model):
         Parse all the fields from the data_model_json
 
         Args:
-            dataset_list(list): Contains list of datasets
-            data_model: Name of the data model
+            dataset_list (list): Contains list of datasets
+            data_model (str): Name of the data model
 
         Yields:
             data_set.DataSet: Dataset object for the given list
@@ -77,6 +78,9 @@ def _parse_constraint(cls, constraint_search):
     def _parse_fields_cluster(self, fields_clusters):
         """
         Parse all the fields from the data_model_json
+
+        Args:
+            fields_clusters (list(list(str))): list of field clusters, each field cluster contains list of field names which are expected to be together
         """
         parsed_fields_clusters = []
         for each_cluster in fields_clusters:
@@ -90,6 +94,9 @@ def _parse_fields_cluster(self, fields_clusters):
     def match_tags(self, addon_tag_list):
         """
         Check if the tags are mapped with this data set
+
+        Args:
+            addon_tag_list (list): list of tags defined in the addon
         """
         for each_tag_group in self.tags:
             if set(each_tag_group).issubset(set(addon_tag_list)):