From c3469772a44b393f69646277a810d81b70b2884c Mon Sep 17 00:00:00 2001 From: Aaron Stephens Date: Mon, 3 Jan 2022 01:04:35 -0800 Subject: [PATCH] docs: fix typos and whitespace --- docs/source/console.rst | 12 ++++++------ docs/source/highlighting.rst | 4 ++-- docs/source/introduction.rst | 4 ++-- docs/source/layout.rst | 4 ++-- docs/source/logging.rst | 2 +- docs/source/markup.rst | 4 ++-- docs/source/pretty.rst | 4 ++-- docs/source/progress.rst | 10 +++++----- docs/source/protocol.rst | 2 +- docs/source/style.rst | 4 ++-- docs/source/syntax.rst | 2 +- docs/source/tables.rst | 2 +- docs/source/text.rst | 2 +- docs/source/traceback.rst | 4 ++-- 14 files changed, 30 insertions(+), 30 deletions(-) diff --git a/docs/source/console.rst b/docs/source/console.rst index 2b26e3104..965fef7ee 100644 --- a/docs/source/console.rst +++ b/docs/source/console.rst @@ -1,7 +1,7 @@ Console API =========== -For complete control over terminal formatting, Rich offers a :class:`~rich.console.Console` class. Most applications will require a single Console instance, so you may want to create one at the module level or as an attribute of your top-level object. For example, you could add a file called "console.py" to your project:: +For complete control over terminal formatting, Rich offers a :class:`~rich.console.Console` class. Most applications will require a single Console instance, so you may want to create one at the module level or as an attribute of your top-level object. For example, you could add a file called "console.py" to your project:: from rich.console import Console console = Console() @@ -52,7 +52,7 @@ To write rich content to the terminal use the :meth:`~rich.console.Console.print console.print(locals()) console.print("FOO", style="white on blue") -You can also use :meth:`~rich.console.Console.print` to render objects that support the :ref:`protocol`, which includes Rich's built in objects such as :class:`~rich.text.Text`, :class:`~rich.table.Table`, and :class:`~rich.syntax.Syntax` -- or other custom objects. +You can also use :meth:`~rich.console.Console.print` to render objects that support the :ref:`protocol`, which includes Rich's built-in objects such as :class:`~rich.text.Text`, :class:`~rich.table.Table`, and :class:`~rich.syntax.Syntax` -- or other custom objects. Logging @@ -170,7 +170,7 @@ Overflow Overflow is what happens when text you print is larger than the available space. Overflow may occur if you print long 'words' such as URLs for instance, or if you have text inside a panel or table cell with restricted space. -You can specify how Rich should handle overflow with the ``overflow`` argument to :meth:`~rich.console.Console.print` which should be one of the following strings: "fold", "crop", "ellipsis", or "ignore". The default is "fold" which will put any excess characters on the following line, creating as many new lines as required to fit the text. +You can specify how Rich should handle overflow with the ``overflow`` argument to :meth:`~rich.console.Console.print` which should be one of the following strings: "fold", "crop", "ellipsis", or "ignore". The default is "fold" which will put any excess characters on the following line, creating as many new lines as required to fit the text. The "crop" method truncates the text at the end of the line, discarding any characters that would overflow. @@ -223,7 +223,7 @@ The Console has a ``style`` attribute which you can use to apply a style to ever Soft Wrapping ------------- -Rich word wraps text you print by inserting line breaks. You can disable this behavior by setting ``soft_wrap=True`` when calling :meth:`~rich.console.Console.print`. With *soft wrapping* enabled any text that doesn't fit will run on to the following line(s), just like the builtin ``print``. +Rich word wraps text you print by inserting line breaks. You can disable this behavior by setting ``soft_wrap=True`` when calling :meth:`~rich.console.Console.print`. With *soft wrapping* enabled any text that doesn't fit will run on to the following line(s), just like the built-in ``print``. Cropping @@ -238,7 +238,7 @@ The :meth:`~rich.console.Console.print` method has a boolean ``crop`` argument. Input ----- -The console class has an :meth:`~rich.console.Console.input` method which works in the same way as Python's builtin :func:`input` function, but can use anything that Rich can print as a prompt. For example, here's a colorful prompt with an emoji:: +The console class has an :meth:`~rich.console.Console.input` method which works in the same way as Python's built-in :func:`input` function, but can use anything that Rich can print as a prompt. For example, here's a colorful prompt with an emoji:: from rich.console import Console console = Console() @@ -263,7 +263,7 @@ Error console The Console object will write to ``sys.stdout`` by default (so that you see output in the terminal). If you construct the Console with ``stderr=True`` Rich will write to ``sys.stderr``. You may want to use this to create an *error console* so you can split error messages from regular output. Here's an example:: - from rich.console import Console + from rich.console import Console error_console = Console(stderr=True) You might also want to set the ``style`` parameter on the Console to make error messages visually distinct. Here's how you might do that:: diff --git a/docs/source/highlighting.rst b/docs/source/highlighting.rst index 260cfbeac..03993190c 100644 --- a/docs/source/highlighting.rst +++ b/docs/source/highlighting.rst @@ -12,8 +12,8 @@ If the default highlighting doesn't fit your needs, you can define a custom high Here's an example which highlights text that looks like an email address:: - from rich.console import Console - from rich.highlighter import RegexHighlighter + from rich.console import Console + from rich.highlighter import RegexHighlighter from rich.theme import Theme class EmailHighlighter(RegexHighlighter): diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst index bcbe906ea..57d19154b 100644 --- a/docs/source/introduction.rst +++ b/docs/source/introduction.rst @@ -10,7 +10,7 @@ Requirements Rich works with OSX, Linux and Windows. -On Windows both the (ancient) cmd.exe terminal is supported and the new `Windows Terminal `_. The later has much improved support for color and style. +On Windows both the (ancient) cmd.exe terminal is supported and the new `Windows Terminal `_. The latter has much improved support for color and style. Rich requires Python 3.6.1 and above. Note that Python 3.6.0 is *not* supported due to lack of support for methods on NamedTuples. @@ -63,7 +63,7 @@ This writes the following output to the terminal (including all the colors and s } -If you would rather not shadow Python's builtin print, you can import ``rich.print`` as ``rprint`` (for example):: +If you would rather not shadow Python's built-in print, you can import ``rich.print`` as ``rprint`` (for example):: from rich import print as rprint diff --git a/docs/source/layout.rst b/docs/source/layout.rst index f23093171..480956311 100644 --- a/docs/source/layout.rst +++ b/docs/source/layout.rst @@ -99,7 +99,7 @@ This will set the upper portion to be exactly 10 rows, no matter the size of the Ratio ----- -In addition to a fixed size, you can also make a flexible layout setting the ``ratio`` argument on the constructor or by assigning to the attribute. The ratio defines how much of the screen the layout should occupy in relation to other layouts. For example, lets reset the size and set the ratio of the upper layout to 2:: +In addition to a fixed size, you can also make a flexible layout setting the ``ratio`` argument on the constructor or by assigning to the attribute. The ratio defines how much of the screen the layout should occupy in relation to other layouts. For example, let's reset the size and set the ratio of the upper layout to 2:: layout["upper"].size = None layout["upper"].ratio = 2 @@ -124,7 +124,7 @@ The top layout is now invisible, and the "lower" layout will expand to fill the layout["upper"].visible = True print(layout) -You could use this to toggle parts of your interface based on your applications configuration. +You could use this to toggle parts of your interface based on your application's configuration. Tree ---- diff --git a/docs/source/logging.rst b/docs/source/logging.rst index 38daaf1f5..2b1d853f6 100644 --- a/docs/source/logging.rst +++ b/docs/source/logging.rst @@ -28,7 +28,7 @@ Similarly, the highlighter may be overridden per log message:: Handle exceptions ------------------- -The :class:`~rich.logging.RichHandler` class may be configured to use Rich's :class:`~rich.traceback.Traceback` class to format exceptions, which provides more context than a builtin exception. To get beautiful exceptions in your logs set ``rich_tracebacks=True`` on the handler constructor:: +The :class:`~rich.logging.RichHandler` class may be configured to use Rich's :class:`~rich.traceback.Traceback` class to format exceptions, which provides more context than a built-in exception. To get beautiful exceptions in your logs set ``rich_tracebacks=True`` on the handler constructor:: import logging diff --git a/docs/source/markup.rst b/docs/source/markup.rst index 1ab925b08..7644bf862 100644 --- a/docs/source/markup.rst +++ b/docs/source/markup.rst @@ -27,7 +27,7 @@ There is a shorthand for closing a style. If you omit the style name from the cl print("[bold red]Bold and red[/] not bold or red") -These markup tags may be use in combination with each other and don't need to be strictly nested. The following examples demonstrates overlapping of markup tags:: +These markup tags may be use in combination with each other and don't need to be strictly nested. The following example demonstrates overlapping of markup tags:: print("[bold]Bold[italic] bold and italic [/bold]italic[/italic]") @@ -86,7 +86,7 @@ If you add an *emoji code* to markup it will be replaced with the equivalent uni >>> print(":warning:") ⚠️ -Some emojis have two variants, the "emoji" variant displays in full color, and the "text" variant displays in monochrome (whatever your default colors are set to). You can specify the variant you want by adding either `"-emoji"` or `"-text"` to the emoji code. Here's an example: +Some emojis have two variants, the "emoji" variant displays in full color, and the "text" variant displays in monochrome (whatever your default colors are set to). You can specify the variant you want by adding either `"-emoji"` or `"-text"` to the emoji code. Here's an example: >>> from rich import print >>> print(":red_heart-emoji:") diff --git a/docs/source/pretty.rst b/docs/source/pretty.rst index 2c1c017dd..7a050b943 100644 --- a/docs/source/pretty.rst +++ b/docs/source/pretty.rst @@ -65,7 +65,7 @@ There are a large number of options to tweak the pretty formatting, See the :cla Rich Repr Protocol ------------------ -Rich is able to syntax highlight any output, but the formatting is restricted to builtin containers, dataclasses, and other objects Rich knows about, such as objects generated by the `attrs `_ library. To add Rich formatting capabilities to custom objects, you can implement the *rich repr protocol*. +Rich is able to syntax highlight any output, but the formatting is restricted to built-in containers, dataclasses, and other objects Rich knows about, such as objects generated by the `attrs `_ library. To add Rich formatting capabilities to custom objects, you can implement the *rich repr protocol*. Run the following command to see an example of what the Rich repr protocol can generate:: @@ -221,7 +221,7 @@ To automatically build a rich repr, use the :meth:`~rich.repr.auto` class decora from rich import print print(BIRDS) -Note that the decorator will also create a `__repr__`, so you you will get an auto-generated repr even if you don't print with Rich. +Note that the decorator will also create a `__repr__`, so you will get an auto-generated repr even if you don't print with Rich. If you want to auto-generate the angular type of repr, then set ``angular=True`` on the decorator:: diff --git a/docs/source/progress.rst b/docs/source/progress.rst index 364ad94ce..1a4e02ed7 100644 --- a/docs/source/progress.rst +++ b/docs/source/progress.rst @@ -59,12 +59,12 @@ Updating tasks When you call :meth:`~rich.progress.Progress.add_task` you get back a `Task ID`. Use this ID to call :meth:`~rich.progress.Progress.update` whenever you have completed some work, or any information has changed. Typically you will need to update ``completed`` every time you have completed a step. You can do this by updated ``completed`` directly or by setting ``advance`` which will add to the current ``completed`` value. -The :meth:`~rich.progress.Progress.update` method collects keyword arguments which are also associated with the task. Use this to supply any additional information you would like to render in the progress display. The additional arguments are stored in ``task.fields`` and may be referenced in :ref:`Column classes`. +The :meth:`~rich.progress.Progress.update` method collects keyword arguments which are also associated with the task. Use this to supply any additional information you would like to render in the progress display. The additional arguments are stored in ``task.fields`` and may be referenced in :ref:`Column classes`. Hiding tasks ~~~~~~~~~~~~ -You can show or hide tasks by updating the tasks ``visible`` value. Tasks are visible by default, but you can also add a invisible task by calling :meth:`~rich.progress.Progress.add_task` with ``visible=False``. +You can show or hide tasks by updating the tasks ``visible`` value. Tasks are visible by default, but you can also add an invisible task by calling :meth:`~rich.progress.Progress.add_task` with ``visible=False``. Transient progress @@ -174,7 +174,7 @@ If you have another Console object you want to use, pass it in to the :class:`~r Redirecting stdout / stderr ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To avoid breaking the progress display visuals, Rich will redirect ``stdout`` and ``stderr`` so that you can use the builtin ``print`` statement. This feature is enabled by default, but you can disable by setting ``redirect_stdout`` or ``redirect_stderr`` to ``False`` +To avoid breaking the progress display visuals, Rich will redirect ``stdout`` and ``stderr`` so that you can use the built-in ``print`` statement. This feature is enabled by default, but you can disable by setting ``redirect_stdout`` or ``redirect_stderr`` to ``False`` Customizing @@ -187,12 +187,12 @@ If the :class:`~rich.progress.Progress` class doesn't offer exactly what you nee class MyProgress(Progress): def get_renderables(self): - yield Panel(self.make_tasks_table(self.tasks)) + yield Panel(self.make_tasks_table(self.tasks)) Multiple Progress ----------------- -You can't have different columns per task with a single Progress instance. However, you can have as many Progress instance as you like in a :ref:`live`. See `live_progress.py `_ and `dynamic_progress.py `_ for examples of using multiple Progress instances. +You can't have different columns per task with a single Progress instance. However, you can have as many Progress instances as you like in a :ref:`live`. See `live_progress.py `_ and `dynamic_progress.py `_ for examples of using multiple Progress instances. Example ------- diff --git a/docs/source/protocol.rst b/docs/source/protocol.rst index 796bed646..cd8c03a4a 100644 --- a/docs/source/protocol.rst +++ b/docs/source/protocol.rst @@ -4,7 +4,7 @@ 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. +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. Use this for presentation or to display additional debugging information that might be hard to parse from a typical ``__repr__`` string. diff --git a/docs/source/style.rst b/docs/source/style.rst index ee9eca5df..c9a5fe92c 100644 --- a/docs/source/style.rst +++ b/docs/source/style.rst @@ -106,7 +106,7 @@ You can parse a style definition explicitly with the :meth:`~rich.style.Style.pa Style Themes ------------ -If you re-use styles it can be a maintenance headache if you ever want to modify an attribute or color -- you would have to change every line where the style is used. Rich provides a :class:`~rich.theme.Theme` class which you can use to define custom styles that you can refer to by name. That way you only need update your styles in one place. +If you re-use styles it can be a maintenance headache if you ever want to modify an attribute or color -- you would have to change every line where the style is used. Rich provides a :class:`~rich.theme.Theme` class which you can use to define custom styles that you can refer to by name. That way you only need to update your styles in one place. Style themes can make your code more semantic, for instance a style called ``"warning"`` better expresses intent that ``"italic magenta underline"``. @@ -132,7 +132,7 @@ To use a style theme, construct a :class:`~rich.theme.Theme` instance and pass i Customizing Defaults ~~~~~~~~~~~~~~~~~~~~ -The Theme class will inherit the default styles builtin to Rich. If your custom theme contains the name of an existing style, it will replace it. This allows you to customize the defaults as easily as you can create your own styles. For instance, here's how you can change how Rich highlights numbers:: +The Theme class will inherit the default styles built-in to Rich. If your custom theme contains the name of an existing style, it will replace it. This allows you to customize the defaults as easily as you can create your own styles. For instance, here's how you can change how Rich highlights numbers:: from rich.console import Console from rich.theme import Theme diff --git a/docs/source/syntax.rst b/docs/source/syntax.rst index 823d345c8..4e55bf996 100644 --- a/docs/source/syntax.rst +++ b/docs/source/syntax.rst @@ -10,7 +10,7 @@ To syntax highlight code, construct a :class:`~rich.syntax.Syntax` object and pr console = Console() with open("syntax.py", "rt") as code_file: - syntax = Syntax(code_file.read(), "python") + syntax = Syntax(code_file.read(), "python") console.print(syntax) You may also use the :meth:`~rich.syntax.Syntax.from_path` alternative constructor which will load the code from disk and auto-detect the file type. The example above could be re-written as follows:: diff --git a/docs/source/tables.rst b/docs/source/tables.rst index 9048334ca..2603e7912 100644 --- a/docs/source/tables.rst +++ b/docs/source/tables.rst @@ -70,7 +70,7 @@ You may also add columns by specifying them in the positional arguments of the : table = Table("Released", "Title", "Box Office", title="Star Wars Movies") -This allows you to specify the text of the column only. If you want to set other attributes, such as width and style, you can add an :class:`~rich.table.Column` class. Here's an example:: +This allows you to specify the text of the column only. If you want to set other attributes, such as width and style, you can add a :class:`~rich.table.Column` class. Here's an example:: from rich.table import Column table = Table( diff --git a/docs/source/text.rst b/docs/source/text.rst index 9d8644f2c..fd6851fb4 100644 --- a/docs/source/text.rst +++ b/docs/source/text.rst @@ -5,7 +5,7 @@ Rich Text Rich has a :class:`~rich.text.Text` class you can use to mark up strings with color and style attributes. You can use a Text instance anywhere a string is accepted, which gives you a lot of control over presentation. -You can consider this class to be like a string with marked up regions of text. Unlike a builtin ``str``, a Text instance is mutable, and most methods operate in-place rather than returning a new instance. +You can consider this class to be like a string with marked up regions of text. Unlike a built-in ``str``, a Text instance is mutable, and most methods operate in-place rather than returning a new instance. One way to add a style to Text is the :meth:`~rich.text.Text.stylize` method which applies a style to a start and end offset. Here is an example:: diff --git a/docs/source/traceback.rst b/docs/source/traceback.rst index 120ca0ceb..f940bbbea 100644 --- a/docs/source/traceback.rst +++ b/docs/source/traceback.rst @@ -18,7 +18,7 @@ The :meth:`~rich.console.Console.print_exception` method will print a traceback try: do_something() - except Exception: + except Exception: console.print_exception(show_locals=True) The ``show_locals=True`` parameter causes Rich to display the value of local variables for each frame of the traceback. @@ -76,7 +76,7 @@ Max Frames A recursion error can generate very large tracebacks that take a while to render and contain a lot of repetitive frames. Rich guards against this with a `max_frames` argument, which defaults to 100. If a traceback contains more than 100 frames then only the first 50, and last 50 will be shown. You can disable this feature by setting `max_frames` to 0. -Here's an example of printing an recursive error:: +Here's an example of printing a recursive error:: from rich.console import Console