Skip to content

Commit 98f6434

Browse files
committed
chore: add logging and console output to developer docs
Signed-off-by: Demolus13 <parth.govale@oracle.com>
1 parent 5bdd3ea commit 98f6434

File tree

1 file changed

+63
-0
lines changed

1 file changed

+63
-0
lines changed

docs/source/pages/developers_guide/style_guide.rst

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,3 +76,66 @@ For variables of a class: we do not use the ``Attribute`` section as per the `nu
7676
x: float
7777
#: The y coordinate of the point.
7878
y: float
79+
80+
81+
--------------------------
82+
Logging and Console Output
83+
--------------------------
84+
85+
Macaron uses the ``rich`` Python library to provide enhanced and well-formatted logging output in the terminal. All logging should be performed using the ``macaron.console`` module.
86+
87+
'''''''''''''''''''''''''
88+
Why use rich for logging?
89+
'''''''''''''''''''''''''
90+
91+
- Provides visually appealing, color-coded, and structured terminal UI.
92+
- Supports custom components like table, progress bar, and panel for complex output.
93+
- Makes it easier to spot errors, progress, failed checks, etc.
94+
95+
''''''''''''''''''''''''''''''
96+
How to use the logging handler
97+
''''''''''''''''''''''''''''''
98+
99+
Import the ``access_handler`` from ``macaron.console`` and use it to set/get the custom rich handler. For simple logging, you can use the handler's methods for info, debug, and error messages.
100+
101+
.. code-block:: python
102+
103+
from macaron.console import access_handler
104+
105+
# Get the RichConsoleHandler
106+
rich_handler = access_handler.get_handler()
107+
108+
# Log an info message
109+
console.info("<info message>")
110+
111+
# Log an debug message
112+
console.debug("<debug message>")
113+
114+
# Log an error message
115+
console.error("<error message>")
116+
117+
To modify the console UI, create a function call which takes necessary information and converts them into Rich RenderableType. Also modify the ``make_layout()`` function to use the newly created rich component.
118+
119+
.. code-block:: python
120+
121+
def update_find_source_table(self, key: str, value: str | Status) -> None:
122+
self.find_source_content[key] = value
123+
find_source_table = Table(show_header=False, box=None)
124+
find_source_table.add_column("Details", justify="left")
125+
find_source_table.add_column("Value", justify="left")
126+
for field, content in self.find_source_content.items():
127+
find_source_table.add_row(field, content)
128+
self.find_source_table = find_source_table
129+
130+
131+
def make_layout(self) -> Group:
132+
layout: list[RenderableType] = []
133+
if self.command == "find-source":
134+
if self.find_source_table.row_count > 0:
135+
layout = layout + [self.find_source_table]
136+
return Group(*layout)
137+
138+
139+
rich_handler.update_find_source_table("<Detail>", "<Value>")
140+
141+
For more advance formatting, refer to the ``rich`` documentation: https://rich.readthedocs.io/en/stable/

0 commit comments

Comments
 (0)