[Docs] Added OR messages glossary

.gitignore

@@ -27,15 +27,13 @@ test/results
 flow
 
 docs/main
+messages.txt
+Messages.md
+MessagesFinal.md
 
 .idea/
 cmake-build-debug/
 debug/
 
 coverage-output
-messages.txt
-Messages.md
-MessagesFinal.md
 .metals/
-
-

README.md

@@ -311,6 +311,11 @@ and their descriptions are available [here](docs/contrib/Logger.md#openroad-tool
 OpenROAD uses Git for version control and contributions. 
 Get familiarised with a quickstart tutorial to contribution [here](GitGuide.md).
 
+
+## Understanding Warning and Error Messages
+Seeing OpenROAD warnings or errors you do not understand? We have compiled a table of all messages
+and you may potentially find your answer [here](docs/user/MessagesFinal.md).
+
 ## License
 
 BSD 3-Clause License. See [LICENSE](LICENSE) file.

docs/conf.py

@@ -153,5 +153,10 @@ def setup(app):
 
     if not os.path.exists('./main'):
         os.symlink('..', './main')
+    # these prefix swaps will be reverted and is needed for sphinx compilation.
     swap_prefix('../README.md', '(docs/', '(../')
     swap_prefix('../README.md', '```mermaid', '```{mermaid}\n:align: center\n')
+
+    # for populating OR Messages page.
+    command = "python getMessages.py"
+    _ = os.popen(command).read()

docs/contrib/GettingInvolved.md

@@ -61,9 +61,9 @@ project like OpenROAD with many application subcomponents, the software
 architecture can quickly get out of control. Changes with lots of new
 dependencies which are not necessary are less likely to be integrated.
 
-If you want to add Tcl code to define a new tool command, look at pdngen
+If you want to add Tcl code to define a new tool command, look at [pdngen](https://github.com/The-OpenROAD-Project/OpenROAD/tree/master/src/pdn)
 as an example of how to do so. Take a look at the
-[cmake file](https://github.com/The-OpenROAD-Project/OpenROAD/blob/master/src/CMakeLists.txt)
+[CMake file](https://github.com/The-OpenROAD-Project/OpenROAD/blob/master/src/CMakeLists.txt)
 which automatically sources the Tcl code and the
 [Tcl file](https://github.com/The-OpenROAD-Project/OpenROAD/blob/master/src/pdn/src/pdn.tcl)
 itself.

docs/contrib/Logger.md

@@ -436,5 +436,21 @@ target_link_libraries(<library_target>
 )
 ```
 
+## Useful Information
+As tool developers, we can also choose to include useful information to the end user - 
+be it in the form on debugging tips, or solutions to fix the errors/warnings. We compile
+a list of such errors in this [table](../user/MessagesFinal.md). The good thing about
+this page is the ability to encode rich formatting using Markdown, enabling you
+to convey more information than what can be said from the limited messages in code.
+
+To format the information, refer to this [sample GRT information file](../main/src/grt/doc/messages/0118.md).
+In addition, make sure you create the corresponding `docs/messages` folder under the `tool` folder, 
+before creating your Markdown file with the corresponding `NUM`. 
+
+```shell
+cd src/<tool> && mkdir -p doc/messages
+cd doc/messages && touch <NUM>.md
+```
+
 ### OpenROAD Tool List
 A full list of tool namespaces can be found [here](DeveloperGuide.md#tool-flow-namespace).

docs/getMessages.py

@@ -0,0 +1,29 @@
+#!/usr/bin/env python3
+
+import os
+
+command = "python ../etc/find_messages.py -d ../src"
+output = os.popen(command).read()
+
+with open('user/MessagesFinal.md', 'w') as f:
+    f.write("# OpenROAD Messages Glossary\n")
+    f.write("Listed below are the OpenROAD warning/errors you may encounter while using the application.\n")
+    f.write("\n")
+    f.write("| Tool | Code | Filename:Line Number | Type | Information             |\n")
+    f.write("| ---- | ---- | -------------------- | ---- | ----------------------- |\n")
+
+    lines = output.split('\n')
+    for line in lines:
+        columns = line.split()
+        if not columns: continue
+        ant = columns[0] 
+        num = columns[1]
+        fileLineNum = f"[{columns[2]}]({columns[-1]})"
+        msgType = columns[-2]
+        tool = columns[0].lower()
+        try:
+            message = open(f"../src/{tool}/doc/messages/{num}.md").read().strip()
+        except OSError as e:
+            message = "-"
+        if not message: message = "-"
+        f.write(f"| {ant} | {num} | {fileLineNum} | {msgType} |{message} |\n")

docs/toc.yml

@@ -72,6 +72,8 @@ entries:
     title: Flute
   - file: main/src/par/README
     title: Partition Manager
+  - file: user/MessagesFinal.md
+    title: Warning and Error Messages Glossary
 
 - file: contrib/GettingInvolved
   title: Getting Involved

etc/find_messages.py

@@ -74,7 +74,7 @@ def parse_args():
 warn_regexp_c = \
     re.compile(r'''
       (?:->|\.)                                        # deref
-      (?:info|warn|fileWarn|error|fileError|critical)  # type
+      (?P<type>info|warn|fileWarn|error|fileError|critical)  # type
       \s*\(\s*                                         # (
       (?:utl::)?(?P<tool>[A-Z]{3})                     # tool
       \s*,\s*                                          # ,
@@ -85,7 +85,7 @@ def parse_args():
 
 warn_regexp_tcl = \
     re.compile(r'''
-      (?:info|warn|error|critical)     # type
+      (?P<type>info|warn|error|critical)     # type
       \s+                              # white-space
       (?P<tool>[A-Z]{3}|"[A-Z]{3}")    # tool
       \s+                              # white-space
@@ -111,11 +111,15 @@ def scan_file(path, file_name, msgs):
         message = match.group('message')
         message = message.rstrip()[1:-1]
         message = re.sub(r'"\s*"', '', message)
+        message_type = match.group('type').upper()
 
         # Count the newlines before the match starts
         line_num = lines[0:match.start()].count('\n') + 1
         position = '{}:{}'.format(file_name, line_num)
-        value = '{:25} {}'.format(position, message)
+        file_link = os.path.join(path, file_name).strip('../').replace('\\','/')
+        file_link = 'https://github.com/The-OpenROAD-Project/OpenROAD/tree/master/{}#L{}'.format(
+                file_link, line_num)
+        value = '{:25} {} {} {}'.format(position, message, message_type, file_link)
 
         msgs[key].add(value)
 

src/grt/doc/messages/0118.md

@@ -0,0 +1 @@
+Do refer to the [GUI guide](https://openroad-flow-scripts.readthedocs.io/en/latest/tutorials/FlowTutorial.html#openroad-gui) and [global routing debugging tips](https://openroad-flow-scripts.readthedocs.io/en/latest/tutorials/FlowTutorial.html#debugging-problems-in-global-routing).

src/grt/doc/messages/0119.md

@@ -0,0 +1 @@
+Do refer to the [GUI guide](https://openroad-flow-scripts.readthedocs.io/en/latest/tutorials/FlowTutorial.html#openroad-gui) and [global routing debugging tips](https://openroad-flow-scripts.readthedocs.io/en/latest/tutorials/FlowTutorial.html#debugging-problems-in-global-routing).