more docs

Makefile

@@ -4,3 +4,6 @@ typecheck:
 	mypy -p rich --python-version 3.7 --ignore-missing-imports --warn-unreachable
 typecheck-report:
 	mypy -p rich --python-version 3.7 --ignore-missing-imports --warn-unreachable --html-report mypy_report
+.PHONY: docs
+docs:
+	cd docs; make html

docs/source/index.rst

@@ -10,6 +10,9 @@ Welcome to Rich's documentation!
    :maxdepth: 2
    :caption: Contents:
 
+   introduction.rst
+   markup.rst
+
    reference.rst
 
 Indices and tables

docs/source/introduction.rst

@@ -0,0 +1,34 @@
+Introduction
+============
+
+Rich is a Python library for rendering *rich* text and formatting to the terminal. Use Rich to create slick command line applications and as a handy debugging aid.
+
+
+Installation
+------------
+
+You may install Rich with your favorite PyPi package manager::
+
+    pip install rich
+
+Add the ``-U`` switch to update to the current version, if rich is already installed.
+
+
+Quick Start
+-----------
+
+The quickest way to get up and running with Rich is to use the alternative ``print`` function, which can be used as a drop-in replacement for Python's built in function. Here's how you would do that::
+
+    from rich import print
+
+You can then print content to the terminal in the same way as usual. Rich will add the time and file/line number where print was called. It will also format and syntax highlight any Python objects you print. 
+
+If you would rather not shadow Python's builtin print, you can import rich.print as ``rprint`` (for example)::
+
+    from rich import print as rprint
+
+For more control over formatting, create a :ref:`rich.console.Console` object::
+
+    from rich.console import Console
+    console = Console()
+    console.print("Hello, **World**! :smiley:")

docs/source/markup.rst

@@ -0,0 +1,35 @@
+Console Markup
+==============
+
+Rich supports a simple markup which you can use to insert color and styles virtually everywhere Rich would accept a string (e.g. :meth:`~rich.console.Console.print` and :meth:`~rich.console.Console.log`).
+
+
+Formatting
+----------
+
+for bold, italic, and strikethrough, Rich uses the same convention as Markdown::
+
+For italics, wrap text in asterisks or underscores. e.g. ``*this is italics*`` or ``_this is also italics_``.
+
+For bold, wrap the text in *two* asterisks or underscores. e.g. ``**this is bold**``or ``__this is also bold__``.
+
+For strikethrough, wrap the text in tildes. e.g. ``~this has a line through it~``.
+
+For code, wrap the text in backticks. e.g. ```import this```
+
+
+Styles
+------
+
+For other styles and color, you can use a syntax similar to bbcode. If you write the style in square brackets, i.e. ``[bold red]``, that style will apply when it is *closed* with a corrensponding ``[/bold red]``.
+
+
+
+Example
+-------
+
+Here's a simple example::
+
+    from rich import print
+    print("Hello, **World**!")
+    print("[bold red]alert![/bold red] *Something happened*")

docs/source/reference.rst

@@ -5,4 +5,6 @@ Reference
    :maxdepth: 3
 
    reference/console.rst
-   
+   reference/emoji.rst
+   reference/highlighter.rst
+   reference/text.rst

docs/source/reference/emoji.rst

@@ -0,0 +1,6 @@
+rich.box
+========
+
+.. automodule:: rich.emoji
+    :members: Emoji
+

docs/source/reference/highlighter.rst

@@ -0,0 +1,7 @@
+rich.highlighter
+================
+
+.. automodule:: rich.highlighter
+    :members:
+    :special-members: __call__
+

docs/source/reference/text.rst

@@ -0,0 +1,6 @@
+rich.text
+=========
+
+.. automodule:: rich.text
+    :members: Text
+

rich/highlighter.py

@@ -11,7 +11,7 @@ class Highlighter(ABC):
         """Highlight a str or Text instance.
         
         Args:
-            text (Union[str, Text]): Text to highlight.
+            text (Union[str, ~Text]): Text to highlight.
         
         Raises:
             TypeError: If not called with text or str.
@@ -22,14 +22,19 @@ class Highlighter(ABC):
         if isinstance(text, str):
             highlight_text = Text(text)
         elif isinstance(text, Text):
-            highlight_text = text
+            highlight_text = text.copy()
         else:
             raise TypeError(f"str or Text instance required, not {text!r}")
-        return self.highlight(highlight_text)
+        self.highlight(highlight_text)
+        return highlight_text
 
     @abstractmethod
-    def highlight(self, text: Text) -> Text:
-        ...
+    def highlight(self, text: Text) -> None:
+        """Apply highlighting in place to text.
+        
+        Args:
+            text (~Text): A text object highlight.
+        """
 
 
 class RegexHighlighter(Highlighter):
@@ -38,7 +43,13 @@ class RegexHighlighter(Highlighter):
     highlights: List[str] = []
     base_style: str = ""
 
-    def highlight(self, text: Text) -> Text:
+    def highlight(self, text: Text) -> None:
+        """Highlight a :ref:`rich.text.Text` using regular expressions.
+        
+        Args:
+            text (Text): Text to highlighted.
+        
+        """
         str_text = str(text)
         base_style = self.base_style
         stylize = text.stylize
@@ -49,10 +60,11 @@ class RegexHighlighter(Highlighter):
                     start, end = _span(name)
                     if start != -1:
                         stylize(start, end, f"{base_style}{name}")
-        return text
 
 
 class ReprHighlighter(RegexHighlighter):
+    """Highlights the text typically produces from ``__repr__`` methods."""
+
     base_style = "repr."
     highlights = [
         r"(?P<brace>[\{\[\(\)\]\}])",