From 6edecd80d93cc82eec4befc5e257416c08b3e4bf Mon Sep 17 00:00:00 2001
From: Will McGugan <willmcgugan@gmail.com>
Date: Fri, 22 Nov 2019 14:42:41 +0000
Subject: [PATCH] docs

---
 rich/console.py | 48 +++++++++++++++++++++++++++++++++---------------
 rich/text.py    | 13 +++++++++++--
 2 files changed, 44 insertions(+), 17 deletions(-)

diff --git a/rich/console.py b/rich/console.py
index e6845a8f..f4f77452 100644
--- a/rich/console.py
+++ b/rich/console.py
@@ -114,32 +114,22 @@ class Console:
         self.style_stack: List[Style] = [default_style]
         self.current_style = default_style
 
-    # def push_styles(self, styles: Dict[str, Style]) -> None:
-    #     """Push a new set of styles on to the style stack.
-
-    #     Args:
-    #         styles (Dict[str, Style]): A mapping of styles.
-
-    #     """
-    #     self._styles.maps.insert(0, styles)
-
-    # def pop_styles(self) -> None:
-    #     if len(self._styles.maps) == 1:
-    #         raise StyleError("Can't pop default styles")
-    #     self._styles.maps.pop(0)
-
     def _enter_buffer(self) -> None:
+        """Enter in to a buffer context, and buffer all output."""
         self._buffer_index += 1
 
     def _exit_buffer(self) -> None:
+        """Leave buffer context, and render content if required."""
         self._buffer_index -= 1
         self._check_buffer()
 
     def __enter__(self) -> Console:
+        """Own context manager to enter buffer context."""
         self._enter_buffer()
         return self
 
     def __exit__(self, exc_type, exc_value, traceback) -> None:
+        """Exit buffer context."""
         self._exit_buffer()
 
     @property
@@ -170,6 +160,15 @@ class Console:
         )
 
     def line(self, count: int = 1) -> None:
+        """Write new line(s).
+        
+        Args:
+            count (int, optional): Number of new lines. Defaults to 1.
+        """
+
+        assert count >= 0, "count must be >= 0"
+        if not count:
+            return
         self.buffer.append(Segment("\n" * count))
         self._check_buffer()
 
@@ -208,6 +207,16 @@ class Console:
     def render_all(
         self, renderables: Iterable[RenderableType], options: Optional[ConsoleOptions]
     ) -> Iterable[Segment]:
+        """Render a number of console objects.
+        
+        Args:
+            renderables (Iterable[RenderableType]): Console objects.
+            options (Optional[ConsoleOptions]): Options for render.
+        
+        Returns:
+            Iterable[Segment]: Segments to be written to the console.
+        
+        """
         render_options = options or self.options
         for renderable in renderables:
             yield from self.render(renderable, render_options)
@@ -248,7 +257,16 @@ class Console:
     def render_str(
         self, text: str, options: ConsoleOptions
     ) -> Iterable[RenderableType]:
-        """Render a string."""
+        """Convert a string to something renderable.
+        
+        Args:
+            text (str): Text to render.
+            options (ConsoleOptions): Options for render.
+        
+        Returns:
+            Iterable[RenderableType]: Renderable objects.
+        
+        """
         if self._markup == "markdown":
             from .markdown import Markdown
 
diff --git a/rich/text.py b/rich/text.py
index 6fa74e44..495c6812 100644
--- a/rich/text.py
+++ b/rich/text.py
@@ -123,6 +123,15 @@ class Text:
 
     @classmethod
     def from_segments(cls, segments: Iterable[Segment]) -> Text:
+        """Convert segments in to a Text object for further processing.
+        
+        Args:
+            segments (Iterable[Segment]): Segments from a rendered console object.
+        
+        Returns:
+            Text: A new text instance.
+        """
+
         text = Text(justify=None)
         append_span = text._spans.append
         append_text = text._text.append
@@ -193,7 +202,7 @@ class Text:
             options (ConsoleOptions): Console options.
         
         Returns:
-            Iterable[Segment]: An iterable of segments.
+            Iterable[Segment]: Result of render that may be written to the console.
         """
 
         text = line.text
@@ -203,7 +212,7 @@ class Text:
 
         def get_style(style: Union[str, Style]) -> Style:
             if isinstance(style, str):
-                return console.parse_style(style)
+                return console.parse_style(style) or Style()
             return style
 
         stack.append(get_style(line.style) if line.style is not None else Style())