Update the template documentation feature

96f0ad50 · Maxime Perrotin · 3483169c · 96f0ad50 · 96f0ad50 · 96f0ad50
Commit 96f0ad50 authored Dec 10, 2019 by Maxime Perrotin
--- a/doc/Makefile
+++ b/doc/Makefile
 all:
 	$(MAKE) -C preprocess
+	cp preprocess/output/order.txt .

 clean:
 	rm -rf preprocess/output/*

--- a/doc/kazoo-merge-doc.py
+++ b/doc/kazoo-merge-doc.py
@@ -48,40 +48,48 @@ def parse_args():
            help='Display debug information')
    parser.add_argument(
            '-o',
-            '--output',
+            '--outputfolder',
            type=str,
-            metavar='out_file',
-            default='updated.mediawiki',
+            metavar='out_folder',
+            default='templates',
            help='Output file name')
    parser.add_argument(
            '-i',
-            '--old',
+            '--oldfolder',
            type=str,
-            default='old.mediawiki',
+            default='./preprocess/output',
            metavar='old',
            help='Previous file containing tags description')
    parser.add_argument(
            '-n',
-            '--new',
+            '--newfolder',
            type=str,
-            default='new.mediawiki',
+            default='./new-templates',
            metavar='new',
            help='Freshly generated tag list')
+    parser.add_argument(
+            '-k',
+            '--orderlist',
+            type=str,
+            default='./order.txt',
+            metavar='order',
+            help='List of ordered template files to be processed')
+
    return parser.parse_args()

-def run(options):
-    old    = options.old
-    new    = options.new
-    result = options.output
-    out_folder = options.output if options.output else '.'
-    #os.makedirs(out_folder, exist_ok=True)
-    if not os.path.exists(old) or not os.path.exists(new):
-        LOG.error ("Input file(s) missing, check --help.")
-        return

+def process_one_file (tmplt: str, old: str, new: str, res_folder: str) -> None:
    #  Read the input files
-    old_content = open (old, "r").readlines()
-    new_content = open (new, "r").readlines()
+    try:
+        old_content = open(old, "r").readlines()
+    except FileNotFoundError:
+        LOG.info("Skipping template " + old + " (file not found)")
+        return
+    try:
+        new_content = open(new, "r").readlines()
+    except FileNotFoundError:
+        LOG.info("Skipping template " + new + " (file not found)")
+        return

    # Build dictionnaries from the content of the two files
    assert len(old_content) > 4 and len(new_content) > 5
@@ -142,9 +150,35 @@ def run(options):

    newdoc.append("|}")

-    with open (result, "w") as output:
+    with open (res_folder+"/"+tmplt, "w") as output:
        output.write("\n".join (newdoc))

+
+def run(options):
+    old_folder    = options.oldfolder
+    new_folder    = options.newfolder
+    result_folder = options.outputfolder
+    os.makedirs(result_folder, exist_ok=True)
+    if not os.path.exists(old_folder):
+        LOG.error ("Input folder(s) missing, check --help - " + old_folder)
+        return
+    if not os.path.exists(new_folder):
+        LOG.error ("Input folder(s) missing, check --help - " + new_folder )
+        return
+
+    if not os.path.exists(options.orderlist):
+        LOG.error ("Missing order specification file " + options.orderlist)
+        return
+
+    orderlist = open(options.orderlist, "r").readlines()
+
+    for each in orderlist:
+        name=each.strip()
+        process_one_file (tmplt=name,
+                         old=old_folder+"/"+name,
+                         new=new_folder+"/"+name,
+                         res_folder=result_folder)
+
 def main():
    ''' Tool entry point '''
    # Catch Ctrl-C to stop the app from the console

--- a/doc/order.txt
+++ b/doc/order.txt
+templates_build_script
+templates_skeletons_makefile
+templates_skeletons_context_parameters
+templates_skeletons_sub_trigger
+templates_skeletons_sub_makefile_filename
+templates_skeletons_sub_function_filename
+templates_skeletons_sub_interface
+templates_skeletons_sub_makefile
+templates_skeletons_sub_function
+templates_concurrency_view_sub_filenode
+templates_concurrency_view_sub_trigger
+templates_concurrency_view_sub_filepart
+templates_concurrency_view_sub_thread
+templates_concurrency_view_sub_filethread
+templates_concurrency_view_sub_fileblock
+templates_concurrency_view_sub_pi
+templates_concurrency_view_sub_ri
+templates_concurrency_view_sub_block
+templates_concurrency_view_sub_partition
+templates_concurrency_view_sub_node
+templates_concurrency_view_sub_system
--- a/doc/preprocess/maker.sh
+++ b/doc/preprocess/maker.sh
@@ -19,5 +19,6 @@ find . -type f -iname '*.post' | \
    while read ANS ; do \
        cat "$ANS" | sed 1d > output/"$(echo ${ANS/.tmplt.post/.post} | sed 's,[/-],_,g')"
    done
-
+sed -i 's,[/-],_,g' output/order.txt
+sed -i 's,\..*,,g' output/order.txt
 rm -rf templates
--- a/doc/templates/templates_concurrency_view_sub_block
+++ b/doc/templates/templates_concurrency_view_sub_block
@@ -2,145 +2,144 @@
 !Parameter name
 !Description
 |-
-|No_Stdlib_Flag
-|@@ADD DESCRIPTION@@
+|Name
+|Protected block name
 |-
-|List_Of_PIs
-|@@ADD DESCRIPTION@@
+|Language
+|Implementation language
 |-
-|Required
-|@@ADD DESCRIPTION@@
+|Calling_Threads
+|List of calling threads
 |-
-|Partition_Name
-|@@ADD DESCRIPTION@@
+|Protected_PIs
+|Protected Provided interfaces (from pi.tmplt)
 |-
 |Unprotected_PIs
-|@@ADD DESCRIPTION@@
+|Unprotected Provided interfaces (from pi.tmplt)
 |-
-|Output_Dir
-|@@ADD DESCRIPTION@@
+|Required
+|Required interfaces (from ri.tmplt)
 |-
-|Calling_Threads
-|@@ADD DESCRIPTION@@
+|Is_Type
+|DOCUMENTATION MISSING
 |-
-|Timer_Resolution
-|@@ADD DESCRIPTION@@
+|Glue
+|DOCUMENTATION MISSING
 |-
-|CP_Names
-|@@ADD DESCRIPTION@@
+|Partition_Name
+|DOCUMENTATION MISSING
 |-
-|CP_Asn1Modules
-|@@ADD DESCRIPTION@@
+|List_Of_RIs
+|DOCUMENTATION MISSING
 |-
-|CP_Asn1Filenames
-|@@ADD DESCRIPTION@@
+|Debug_Flag
+|DOCUMENTATION MISSING
 |-
-|Has_Context
-|@@ADD DESCRIPTION@@
+|CP_Values
+|DOCUMENTATION MISSING
 |-
-|Timers
-|@@ADD DESCRIPTION@@
+|List_Of_PIs
+|DOCUMENTATION MISSING
 |-
-|ASync_RI_Param_Type
-|@@ADD DESCRIPTION@@
+|List_Of_Sync_RIs
+|DOCUMENTATION MISSING
 |-
-|Async_RIs_Parent
-|@@ADD DESCRIPTION@@
+|List_Of_ASync_RIs
+|DOCUMENTATION MISSING
 |-
-|Language
-|@@ADD DESCRIPTION@@
+|ASync_PI_Param_Name
+|DOCUMENTATION MISSING
 |-
-|Is_Type
-|@@ADD DESCRIPTION@@
+|Check_Data_View
+|DOCUMENTATION MISSING
 |-
-|CP_Types
-|@@ADD DESCRIPTION@@
+|Sync_RIs_Parent
+|DOCUMENTATION MISSING
 |-
 |Zip_File
-|@@ADD DESCRIPTION@@
+|DOCUMENTATION MISSING
 |-
-|Check_Data_View
-|@@ADD DESCRIPTION@@
+|Binary_Path
+|DOCUMENTATION MISSING
 |-
-|PIs_Have_Params
-|@@ADD DESCRIPTION@@
+|List_Of_Sync_PIs
+|DOCUMENTATION MISSING
 |-
 |Property_Values
-|@@ADD DESCRIPTION@@
+|DOCUMENTATION MISSING
 |-
-|ASync_PI_Param_Name
-|@@ADD DESCRIPTION@@
-|-
-|List_Of_Sync_RIs
-|@@ADD DESCRIPTION@@
+|ASync_RI_Param_Type
+|DOCUMENTATION MISSING
 |-
-|Binary_Path
-|@@ADD DESCRIPTION@@
+|Node_Name
+|DOCUMENTATION MISSING
 |-
-|RIs_Have_Params
-|@@ADD DESCRIPTION@@
+|Has_Context
+|DOCUMENTATION MISSING
 |-
-|List_Of_Sync_PIs
-|@@ADD DESCRIPTION@@
+|No_Stdlib_Flag
+|DOCUMENTATION MISSING
 |-
-|Instance_Of
-|@@ADD DESCRIPTION@@
+|Data_View
+|DOCUMENTATION MISSING
 |-
-|CP_Values
-|@@ADD DESCRIPTION@@
+|Output_Dir
+|DOCUMENTATION MISSING
 |-
-|ASync_RI_Param_Name
-|@@ADD DESCRIPTION@@
+|ASync_PI_Param_Type
+|DOCUMENTATION MISSING
 |-
-|Property_Names
-|@@ADD DESCRIPTION@@
+|Timer_Resolution
+|DOCUMENTATION MISSING
 |-
-|Sync_RIs_Parent
-|@@ADD DESCRIPTION@@
+|Async_RIs_Parent
+|DOCUMENTATION MISSING
 |-
-|Data_View
-|@@ADD DESCRIPTION@@
+|Use_POHIC
+|DOCUMENTATION MISSING
 |-
-|List_Of_ASync_RIs
-|@@ADD DESCRIPTION@@
+|Timers
+|DOCUMENTATION MISSING
 |-
-|Protected_PIs
-|@@ADD DESCRIPTION@@
+|CP_Types
+|DOCUMENTATION MISSING
 |-
-|Debug_Flag
-|@@ADD DESCRIPTION@@
+|Deployment_View
+|DOCUMENTATION MISSING
 |-
-|Skeletons
-|@@ADD DESCRIPTION@@
+|Interface_View
+|DOCUMENTATION MISSING
 |-
-|Glue
-|@@ADD DESCRIPTION@@
+|Instance_Of
+|DOCUMENTATION MISSING
 |-
-|Node_Name
-|@@ADD DESCRIPTION@@
+|ASync_RI_Param_Name
+|DOCUMENTATION MISSING
 |-
-|List_Of_ASync_PIs
-|@@ADD DESCRIPTION@@
+|Skeletons
+|DOCUMENTATION MISSING
 |-
-|Name
-|@@ADD DESCRIPTION@@
+|CP_Names
+|DOCUMENTATION MISSING
 |-
-|Interface_View
-|@@ADD DESCRIPTION@@
+|List_Of_ASync_PIs
+|DOCUMENTATION MISSING
 |-
-|Use_POHIC
-|@@ADD DESCRIPTION@@
+|RIs_Have_Params
+|DOCUMENTATION MISSING
 |-
-|ASync_PI_Param_Type
-|@@ADD DESCRIPTION@@
+|CP_Asn1Filenames
+|DOCUMENTATION MISSING
 |-
 |Other_Files
-|@@ADD DESCRIPTION@@
+|DOCUMENTATION MISSING
 |-
-|List_Of_RIs
-|@@ADD DESCRIPTION@@
+|Property_Names
+|DOCUMENTATION MISSING
 |-
-|Deployment_View
-|@@ADD DESCRIPTION@@
+|CP_Asn1Modules
+|DOCUMENTATION MISSING
 |-
-|}
+|PIs_Have_Params
+|DOCUMENTATION MISSING
+|}
\ No newline at end of file
--- a/doc/templates/templates_concurrency_view_sub_file_block
+++ b/doc/templates/templates_concurrency_view_sub_file_block
-{| class="wikitable"
-!Parameter name
-!Description
-|-
-|Block_Name
-|@@ADD DESCRIPTION@@
-|-
-|}
--- a/doc/templates/templates_concurrency_view_sub_file_node
+++ b/doc/templates/templates_concurrency_view_sub_file_node
-{| class="wikitable"
-!Parameter name
-!Description
-|-
-|Node_Name
-|@@ADD DESCRIPTION@@
-|-
-|}
--- a/doc/templates/templates_concurrency_view_sub_file_part
+++ b/doc/templates/templates_concurrency_view_sub_file_part
-{| class="wikitable"
-!Parameter name
-!Description
-|-
-|Partition_Name
-|@@ADD DESCRIPTION@@
-|-
-|}
--- a/doc/templates/templates_concurrency_view_sub_file_thread
+++ b/doc/templates/templates_concurrency_view_sub_file_thread
-{| class="wikitable"
-!Parameter name
-!Description
-|-
-|Thread_Name
-|@@ADD DESCRIPTION@@
-|-
-|}
--- a/doc/templates/templates_concurrency_view_sub_node
+++ b/doc/templates/templates_concurrency_view_sub_node
@@ -2,49 +2,48 @@
 !Parameter name
 !Description
 |-
+|Node_Name
+|Name of the node from deployment view
+|-
 |Partition_Names
-|@@ADD DESCRIPTION@@
+|Tag listing the partitions in this node
 |-
-|VP_Classifiers
-|@@ADD DESCRIPTION@@
+|Has_Memory
+|Boolean flag indicating that a memory is defined for this node
 |-
 |Partitions
-|@@ADD DESCRIPTION@@
+|List of rendered code for partitions
 |-
 |VP_Names
-|@@ADD DESCRIPTION@@
-|-
-|Package_Name
-|@@ADD DESCRIPTION@@
+|Vector tag: list of virtual processors on this node
 |-
 |VP_Package_Names
-|@@ADD DESCRIPTION@@
-|-
-|CPU_Family
-|@@ADD DESCRIPTION@@
+| |_ Corresponding package name
 |-
 |VP_Platforms
-|@@ADD DESCRIPTION@@
-|-
-|CPU_Classifier
-|@@ADD DESCRIPTION@@
-|-
-|CPU_Instance
-|@@ADD DESCRIPTION@@
+| |_ Corresponding platform name
 |-
-|CPU_Name
-|@@ADD DESCRIPTION@@
+|VP_Classifiers
+| |_ Corresponding aadl classifier
 |-
 |Ada_Runtime
-|@@ADD DESCRIPTION@@
+|DOCUMENTATION MISSING
+|-
+|Package_Name
+|DOCUMENTATION MISSING
 |-
 |CPU_Platform
-|@@ADD DESCRIPTION@@
+|DOCUMENTATION MISSING
 |-
-|Node_Name
-|@@ADD DESCRIPTION@@
+|CPU_Family
+|DOCUMENTATION MISSING
 |-
-|Has_Memory
-|@@ADD DESCRIPTION@@
+|CPU_Name
+|DOCUMENTATION MISSING
 |-
-|}
+|CPU_Classifier
+|DOCUMENTATION MISSING
+|-
+|CPU_Instance
+|DOCUMENTATION MISSING
+|}
\ No newline at end of file
--- a/doc/templates/templates_concurrency_view_sub_partition
+++ b/doc/templates/templates_concurrency_view_sub_partition
@@ -2,109 +2,108 @@
 !Parameter name
 !Description
 |-
-|VP_Package_Name
-|@@ADD DESCRIPTION@@
-|-
-|In_Port_Type_Name
-|@@ADD DESCRIPTION@@
-|-
-|Thread_Has_Param
-|@@ADD DESCRIPTION@@
-|-
-|Block_Languages
-|@@ADD DESCRIPTION@@
-|-
-|Thread_Src_Port
-|@@ADD DESCRIPTION@@
-|-
-|Connected_Threads
-|@@ADD DESCRIPTION@@
+|Name
+|Partition name (usually the name of the binary)
 |-
-|VP_Name
-|@@ADD DESCRIPTION@@
+|Threads
+|Code generated for the threads
 |-
-|Thread_Src_Name
-|@@ADD DESCRIPTION@@
+|Thread_Names
+|Tag: list of thread names
 |-
-|In_Port_Thread_Name
-|@@ADD DESCRIPTION@@
+|Node_Name
+|Name of the node containing this partition
 |-
-|Part_Out_Port_Name
-|@@ADD DESCRIPTION@@
+|Blocks
+|Code generated for protected functions
 |-
 |Block_Names
-|@@ADD DESCRIPTION@@
+|Tag: list of block (user functions) names
+|-
+|Coverage
+|True if user requested code coverage enable
 |-
 |Package_Name
-|@@ADD DESCRIPTION@@
+|AADL Package name for the target (e.g. ocarina_porocessors_x86)
 |-
-|Blocks
-|@@ADD DESCRIPTION@@
+|CPU_Name
+|CPU AADL Identifier (e.g. x86_inst)
 |-
 |CPU_Family
-|@@ADD DESCRIPTION@@
-|-
-|CPU_Classifier
-|@@ADD DESCRIPTION@@
+|CPU Kind (e.g. leon3)
 |-
-|Block_Instance_Of
-|@@ADD DESCRIPTION@@
+|CPU_Instance
+|AADL component instance (e.g. rtems_posix)
 |-
-|Memory_Region
-|@@ADD DESCRIPTION@@
+|CPU_Platform
+|AADL CPU_Platform (e.g. PLATFORM_NATIVE)
 |-
-|Thread_Names
-|@@ADD DESCRIPTION@@
+|CPU_Classifier
+|AADL CPU Classifier (e.g. ocarina_processors_x86::x86.linux)
 |-
-|Threads
-|@@ADD DESCRIPTION@@
+|VP_Name
+|Virtual processor name on which the partition is bounded
 |-
 |VP_Platform
-|@@ADD DESCRIPTION@@
+|Virtual processor platform (e.g. PLATFORM_AIR)
 |-
-|Coverage
-|@@ADD DESCRIPTION@@
+|VP_Classifier
+|Virtual processor classifier
 |-
-|CPU_Instance
-|@@ADD DESCRIPTION@@
+|Bound_Functions
+|List of user functions from Interface view
+|-
+|Thread_Src_Name
+|Vector tag : connection thread name (source)
 |-
 |Thread_Dst_Name
-|@@ADD DESCRIPTION@@
+|Vector tag : connection thread name (dest)
 |-
-|VP_Duration
-|@@ADD DESCRIPTION@@
+|Thread_Src_Port
+|Vector tag : connection port name (source)
 |-
-|In_Port_Names
-|@@ADD DESCRIPTION@@
+|Thread_Dst_Port
+|Vector tag : connection port name (dest)
 |-
-|CPU_Name
-|@@ADD DESCRIPTION@@
+|In_Port_Names
+|Vector tag: input ports of the partition
 |-
-|Thread_Dst_Port
-|@@ADD DESCRIPTION@@
+|In_Port_Thread_Name
+| |_ corresponding thread inside the partition
 |-
-|