From 24f3ff4d60cece736435a4533aebb854fc86cb45 Mon Sep 17 00:00:00 2001 From: Will McGugan Date: Sun, 29 Dec 2019 18:03:42 +0000 Subject: [PATCH] more docs --- Makefile | 3 +++ docs/source/index.rst | 3 +++ docs/source/introduction.rst | 34 ++++++++++++++++++++++++++ docs/source/markup.rst | 35 +++++++++++++++++++++++++++ docs/source/reference.rst | 4 ++- docs/source/reference/emoji.rst | 6 +++++ docs/source/reference/highlighter.rst | 7 ++++++ docs/source/reference/text.rst | 6 +++++ rich/highlighter.py | 26 ++++++++++++++------ 9 files changed, 116 insertions(+), 8 deletions(-) create mode 100644 docs/source/introduction.rst create mode 100644 docs/source/markup.rst create mode 100644 docs/source/reference/emoji.rst create mode 100644 docs/source/reference/highlighter.rst create mode 100644 docs/source/reference/text.rst diff --git a/Makefile b/Makefile index 47db2603..09b22698 100644 --- a/Makefile +++ b/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 diff --git a/docs/source/index.rst b/docs/source/index.rst index ffeb8344..fd2d6acd 100644 --- a/docs/source/index.rst +++ b/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 diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst new file mode 100644 index 00000000..96d8d36b --- /dev/null +++ b/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:") \ No newline at end of file diff --git a/docs/source/markup.rst b/docs/source/markup.rst new file mode 100644 index 00000000..fa34b4ac --- /dev/null +++ b/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*") diff --git a/docs/source/reference.rst b/docs/source/reference.rst index a88fe79d..b257b0d6 100644 --- a/docs/source/reference.rst +++ b/docs/source/reference.rst @@ -5,4 +5,6 @@ Reference :maxdepth: 3 reference/console.rst - \ No newline at end of file + reference/emoji.rst + reference/highlighter.rst + reference/text.rst diff --git a/docs/source/reference/emoji.rst b/docs/source/reference/emoji.rst new file mode 100644 index 00000000..bcaa6613 --- /dev/null +++ b/docs/source/reference/emoji.rst @@ -0,0 +1,6 @@ +rich.box +======== + +.. automodule:: rich.emoji + :members: Emoji + diff --git a/docs/source/reference/highlighter.rst b/docs/source/reference/highlighter.rst new file mode 100644 index 00000000..7f5a11ff --- /dev/null +++ b/docs/source/reference/highlighter.rst @@ -0,0 +1,7 @@ +rich.highlighter +================ + +.. automodule:: rich.highlighter + :members: + :special-members: __call__ + diff --git a/docs/source/reference/text.rst b/docs/source/reference/text.rst new file mode 100644 index 00000000..76b41f4b --- /dev/null +++ b/docs/source/reference/text.rst @@ -0,0 +1,6 @@ +rich.text +========= + +.. automodule:: rich.text + :members: Text + diff --git a/rich/highlighter.py b/rich/highlighter.py index 6baf61f4..877516c5 100644 --- a/rich/highlighter.py +++ b/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[\{\[\(\)\]\}])",