docs

docs/source/appendix/box.rst

@@ -1,8 +1,14 @@
-.. _appendix-box:
+.. _appendix_box:
 
 Box
 ===
 
+Rich defines a number of ways of drawing boxes and lines such as those used in tables. To select a box style import one of the constants below from rich.box. For example::
+
+    from rich import box
+    table = Table(box=box.SQUARE)
+
+The constants are as follows:
 
 .. raw:: html
 

docs/source/index.rst

@@ -11,9 +11,9 @@ Welcome to Rich's documentation!
    :caption: Contents:
 
    introduction.rst
-   console.rst
-   markup.rst
+   console.rst   
    style.rst
+   markup.rst
    tables.rst
    markdown.rst
    syntax.rst

docs/source/reference/table.rst

@@ -2,5 +2,4 @@ rich.table
 ==========
 
 .. automodule:: rich.table
-    :members: Table
-
+    :members:

docs/source/style.rst

@@ -62,3 +62,21 @@ It is slightly quicker to construct a Style class like this, since a style defin
 
 You can parse a style definition explicitly with the :meth:`~rich.style.Style.parse` method.
 
+
+Custom Styles
+-------------
+
+While it is possible to explicitly specify styles each time you use them, it is discouraged. Rich allows you to predefine style names which you can use in place on an explicit style. For instance, you may want to define styles for info, warning, danger etc.
+
+You can define a mapping of names to styles in the :class:`~rich.console.Console` constructor. These styles will be merged in to the default styles, potentially overwriting them. Here's an example::
+
+    from rich.console import Console
+    styles = {
+        "info" : Style.parse("dim cyan"),
+        "warning": Style.parse("magenta"),
+        "danger": Style.parse("bold red")
+    }
+    console = Console(styles=styles)
+    console.print("This is information", style="info")
+    console.print("Something terrible happened!", style="danger")
+

docs/source/tables.rst

@@ -22,7 +22,7 @@ Here's an example::
     table.add_row("Dec 16, 2016", "Rouge One: A Star Wars Story", "$1,332,439,889")
 
     console = Console()
-    console.print(table)    
+    console.print(table)
 
 This produces the following output:
 

docs/source/text.rst

@@ -1,3 +1,20 @@
 Rich Text
 =========
 
+Rich has a :class:`~rich.text.Text` class for text that may be marked up with color and style attributes. You can consider this class to be like a mutable string with style information. The methods on the Text() instance are similar to a Python ``str`` but are designed to preserve any style information.
+
+One way to add a style to Text is the :meth:`~tich.text.Text.styleize` method which applies a style to a start and end offset. Here is an example::
+
+    from rich.text import Text
+    text = Text("Hello, World!")
+    text.styleize(0, 6, "bold magenta")
+    console.print(text)
+
+This will print "Hello, World!" to the terminal, with the first word in bold.
+
+Alternatively, you can construct style text by calling :meth:`~rich.text.Text.append` to add a string and style to the end of the Text. Here's an example::
+
+    text = Text()
+    text.append("Hello", style="bold magenta")
+    text.append(" World!")
+    console.print(text)

rich/console.py

@@ -189,7 +189,6 @@ def __init__(
         log_time_format: str = "[%X] ",
         highlighter: "HighlighterType" = ReprHighlighter(),
     ):
-
         self._styles = ChainMap(DEFAULT_STYLES if styles is None else styles)
         self.file = file or sys.stdout
         self._width = width

rich/highlighter.py

@@ -49,10 +49,10 @@ class RegexHighlighter(Highlighter):
     base_style: str = ""
 
     def highlight(self, text: Text) -> None:
-        """Highlight a :ref:`rich.text.Text` using regular expressions.
+        """Highlight :class:`rich.text.Text` using regular expressions.
         
         Args:
-            text (Text): Text to highlighted.
+            text (~Text): Text to highlighted.
         
         """
         str_text = str(text)
@@ -68,7 +68,7 @@ def highlight(self, text: Text) -> None:
 
 
 class ReprHighlighter(RegexHighlighter):
-    """Highlights the text typically produces from ``__repr__`` methods."""
+    """Highlights the text typically produced from ``__repr__`` methods."""
 
     base_style = "repr."
     highlights = [

rich/table.py

@@ -82,6 +82,27 @@ class _Cell(NamedTuple):
 
 
 class Table:
+    """A console renderable to draw a table.
+    
+    Args:
+        title (Union[str, Text], optional): The title of the table rendered at the top. Defaults to None.
+        caption (Union[str, Text], optional): The table caption rendered below. Defaults to None.
+        width (int, optional): The width in characters of the table, or ``None`` to automatically fit. Defaults to None.
+        box (Optional[box.Box], optional): One of the constants in box.py used to draw the edges (See :ref:`appendix_box`). Defaults to box.HEAVY_HEAD.
+        padding (PaddingDimensions, optional): Padding for cells (top, right, bottom, left). Defaults to (0, 1).
+        pad_edge (bool, optional): Enable padding of edge cells. Defaults to True.
+        expand (bool, optional): Expand the table to fit the available space if ``True`` otherwise the table width will be auto-calculated. Defaults to False.
+        show_header (bool, optional): Show a header row. Defaults to True.
+        show_footer (bool, optional): Show a footer row. Defaults to False.
+        show_edge (bool, optional): Draw a box around the outside of the table. Defaults to True.
+        style (Union[str, Style], optional): Default style for the table. Defaults to "none".
+        header_style (Union[str, Style], optional): Style of the header. Defaults to None.
+        footer_style (Union[str, Style], optional): Style of the footer. Defaults to None.
+        border_style (Union[str, Style], optional): Style of the border. Defaults to None.
+        title_style (Union[str, Style], optional): Style of the title. Defaults to None.
+        caption_style (Union[str, Style], optional): Style of the caption. Defaults to None.
+    """
+
     columns: List[Column]
 
     def __init__(
@@ -104,6 +125,7 @@ def __init__(
         title_style: Union[str, Style] = None,
         caption_style: Union[str, Style] = None,
     ) -> None:
+
         self.columns = [
             (Column(header) if isinstance(header, str) else header)
             for header in headers
@@ -181,6 +203,11 @@ def add_column(
         self.columns.append(column)
 
     def add_row(self, *renderables: Optional[Union[str, "ConsoleRenderable"]]) -> None:
+        """Add a row of renderables.
+        
+        Raises:
+            errors.NotRenderableError: If you add something that can't be rendered.
+        """
         from .console import ConsoleRenderable
 
         def add_cell(column: Column, renderable: ConsoleRenderable):
@@ -235,6 +262,7 @@ def __console__(
         yield from self.render_caption(table_width)
 
     def render_title(self, table_width: int) -> "RenderResult":
+        """Render the title. Override if you want to render the title differently."""
         if self.title:
             if isinstance(self.title, str):
                 title_text = Text.from_markup(
@@ -245,6 +273,7 @@ def render_title(self, table_width: int) -> "RenderResult":
             yield title_text.wrap(table_width, "center")
 
     def render_caption(self, table_width: int) -> "RenderResult":
+        """Render the caption. Override if you want to render the caption differently."""
         if self.caption:
             if isinstance(self.caption, str):
                 caption_text = Text.from_markup(

rich/text.py

@@ -83,7 +83,7 @@ def right_crop(self, offset: int) -> "Span":
 
 
 class Text:
-    """Text with color / style.
+    r"""Text with color / style.
         
         Args:
             text (str, optional): Default unstyled text. Defaults to "".
@@ -375,7 +375,7 @@ def append(
             raise TypeError("Only str or Text can be appended to Text")
 
     def split(self, separator="\n", include_separator: bool = False) -> Lines:
-        """Split rich text in to lines, preserving styles.
+        r"""Split rich text in to lines, preserving styles.
         
         Args:
             separator (str, optional): String to split on. Defaults to "\n".