docs

docs/source/protocol.rst

@@ -0,0 +1,37 @@
+Console Protocol
+================
+
+Rich supports a simple protocol to add rich formatting capabilities to custom objects, so you can  :meth:`~rich.console.Console.print` your object with color, styles and formatting.
+
+You can use this for presentation or to display additional debugging information that might be hard to parse from a ``__repr__`` output.
+
+
+Console Str
+-----------
+
+The easiest way to add console output to your custom object is to implement a ``__console_str__`` method. This method accepts no arguments, and should return a :class:`~rich.text.Text` instance. Here's an example::
+
+    class MyObject:
+        def __console_str__(self) -> Text:
+            return Text.from_markup("[bold]MyObject()[/bold]")
+
+If you were to print or log an instance of ``MyObject`` it would render as ``MyObject()`` in bold. Naturally, you would want to put this to better use, perhaps by adding specialized syntax highlighting.
+
+
+Console Render
+--------------
+
+The ``__console_str__`` method is limited to styled text. For more advanced rendering, Rich supports a ``__console__`` method which you can use to render custom output with other renderable objects. For instance, a complex data type might be best represented as a :class:`~rich.table.Table`.
+
+The ``__console__`` method should accept a :class:`~rich.console.Console` and a :class:`~rich.console.ConsoleOptions` instance. It should return an iterable of other renderable objects. Although that means it *could* return a container such as a list, it is customary to ``yield`` output (making the method a generator)
+
+Here's an example of a ``__console__`` method::
+
+    class MyObject:
+        def __console__(self, console: Console, options: ConsoleOptions) -> Iterable[Table]:
+            my_table = Table("Key, "Value")
+            my_table.add_row("foo", "bar")
+            my_table.add_row("egg", "baz")
+            yield my_table
+
+If you were to print a ``MyObject`` instance, it would render a simple table to the terminal.