Improve doc quality and add error.rst.

Author: Tim-ats-d

doc/source/api.rst

@@ -5,4 +5,5 @@ API documentation
   :maxdepth: 2
 
   visualdialog.rst
+  error.rst
   utils.rst

doc/source/error.rst

@@ -0,0 +1,8 @@
+Exceptions
+==========
+
+**Visual-dialog** defined several exceptions raised by library. 
+
+.. autoexception:: visualdialog.error.ValueNotInBound
+
+.. autoexception:: visualdialog.error.PanicError

doc/source/visualdialog.rst

@@ -2,7 +2,7 @@ Text boxes
 ==========
 
 .. important::
-  This library provides two classes but only :class:`DialogBox` is destined to be instantiated.
+  **Visual-dialog** provides two classes but only :class:`DialogBox` is destined to be instantiated.
 
 BaseTextBox
 -----------
@@ -11,15 +11,11 @@ BaseTextBox
 
   .. automethod:: __init__
 
-  The following variables are instance attributes:
-
-  .. autoattribute:: confirm_keys
-
   The following methods are public:
 
-  .. py:property:: position
+  .. autoproperty:: position
 
-  .. py:property:: dimensions
+  .. autoproperty:: dimensions
 
   .. automethod:: framing_box
 

visualdialog/box.py

@@ -6,7 +6,7 @@
 import curses
 import curses.textpad
 import functools
-from typing import Callable, List, Literal, Sequence, Tuple, Union
+from typing import Callable, List, Literal, Optional, Sequence, Tuple, Union
 
 from .error import PanicError, ValueNotInBound
 from .type import CursesKey, CursesTextAttribute, CursesTextAttributes, CursesWindow
@@ -68,7 +68,7 @@ class BaseTextBox:
     :param title_colors_pair_nb:
         Number of the curses color pair that will be used to color the
         title. Zero corresponding to the pair of white color on black
-        background initialized by ``curses``). This defaults to ``0``.
+        background initialized by ``curses``. This defaults to ``0``.
 
     :param title_text_attr:
         Dialog box title text attributes. It should be a single curses
@@ -85,7 +85,15 @@ class BaseTextBox:
         in ``downtime_chars``.
         This defaults to ``600``.
 
-    :ivar var2: initial value: par2
+    :ivar key_detection: initial value: ["getkey", "getch", "get_wch"]:
+        Keystroke acquisition ``curses`` method for
+        :meth:`BaseTextBox.get_input`.
+
+    :ivar confirm_keys: initial value: [" "]:
+        List of accepted key to skip dialog.
+
+    :ivar panic_keys: initial value: []:
+        List of accepted key to raise :exc:`PanicError`.
     """
     @value_checker
     def __init__(
@@ -94,7 +102,7 @@ def __init__(
             pos_y: int,
             height: int,
             width: int,
-            title: str = "",
+            title: Optional[str] = None,
             title_colors_pair_nb: int = 0,
             title_text_attr: Union[CursesTextAttribute,
                                    CursesTextAttributes] = curses.A_BOLD,
@@ -122,19 +130,9 @@ def __init__(
         self.downtime_chars = downtime_chars
         self.downtime_chars_delay = downtime_chars_delay
 
-        #: Keystroke acquisition ``curses`` method for
-        #: :method:`BaseTextBox.get_input`.
-        self.key_detection: Literal["getkey",
-                                    "getch",
-                                    "get_wch"] = "getkey"
-
-        #: List of accepted key to skip dialog.
-        #: This defaults `[" "]`.
+        self.key_detection: Literal["getkey", "getch", "get_wch"] = "getkey"
         self.confirm_keys: List[CursesKey] = [" "]
-
         self.panic_keys: List[CursesKey] = []
-        #: List of accepted key to raise :exception:PanicError.
-        #: This defaults to an empty list.
 
     @property
     def position(self) -> Tuple[int, int]:
@@ -199,7 +197,7 @@ def get_input(self, win: CursesWindow):
         ``self.confirm_keys`` is not detected.
 
         The method of key detection depends on the variable
-        ``self.key_detection_mode``.
+        ``self.key_detection``.
 
         :param win: ``curses`` window object on which the method will
             have effect.

visualdialog/dialog.py

@@ -25,15 +25,7 @@ class DialogBox(BaseTextBox):
         can lead to an overflow of the dialog box frame. This defaults
         to ``"►"``.
 
-<<<<<<< HEAD
-    :key kwargs: Keyword arguments correspond to the instance attributes
-        of :class:`BaseTextBox`.
-
-    .. NOTE::
-        This class inherits of :class:`BaseTextBox`.
-=======
     :param args: Constructor arguments of :class:`BaseTextBox`.
->>>>>>> 817377f (DialogBox.char_by_char and word_by_word nows return given text argument, start to improve doc.)
 
     :param kwargs: Constructor keyword arguments of
         :class:`BaseTextBox`.
@@ -82,10 +74,7 @@ def __enter__(self) -> "DialogBox":
 
     def __exit__(self, type, value, traceback):
         """Return None."""
-<<<<<<< HEAD
         return None
-=======
->>>>>>> 817377f (DialogBox.char_by_char and word_by_word nows return given text argument, start to improve doc.)
 
     def char_by_char(self,
                      win: CursesWindow,
@@ -143,42 +132,20 @@ def char_by_char(self,
             number generated in ``random_delay`` interval. This defaults
             to ``(0, 0)``.
 
-        :param callback: Iterable of callable called one by one after
+        :param callbacks: Iterable of callable called one by one after
             writing a character and the delay time has elapsed. This
             defaults to an empty tuple.
             The arguments passed to the given callables are:
-                - the current instance (``self``).
-                - the character previously written.
-                - the index of the character previously written in the
-                  word being written.
-
-<<<<<<< HEAD
-        :returns: ``text`` argument passed in parameter without any
-            treatment.
-
-        .. NOTE::
-            Method flow:
-                - Calling ``framing_box`` method.
-                - Flash screen depending ``flash_screen`` parameter.
-                - Cutting text into line to stay within the dialog box
-                  frame.
-                - Writing paragraph by paragraph.
-                - Writing each line of the current paragraph.
-                - Writing each word of line.
-                - Writing each character of word and execute callbacks
-                  between.
-                - Waits until a key contained in the class attribute
-                  ``confirm_keys`` was pressed before writing the
-                  following paragraph.
-                - Complete cleaning ``win``.
-
-        .. WARNING::
-=======
+
+            * the current instance (``self``).
+            * the character previously written.
+            * the index of the character previously written in the
+              word being written.
+
         .. note::
             See implementation for more informations on method flow.
 
         .. note::
->>>>>>> 817377f (DialogBox.char_by_char and word_by_word nows return given text argument, start to improve doc.)
             If the volume of text displayed is too large to be contained
             in a dialog box, text will be automatically cut into
             paragraphs using ``textwrap.wrap`` function. See
@@ -260,38 +227,18 @@ def word_by_word(self,
             generated in ``random_delay`` interval. This defaults to
             ``(0, 0)``.
 
-        :param callback: Iterable of callable called one by one after
+        :param callbacks: Iterable of callable called one by one after
             writing a word and the delay time has elapsed. This defaults
             to an empty tuple.
             The arguments passed to the given callables are:
-                - the current instance (``self``).
-                - the word previously written.
-
-<<<<<<< HEAD
-        :returns: ``text`` argument passed in parameter without any
-            treatment.
-
-        .. NOTE::
-            Method flow:
-                - Calling ``framing_box`` method.
-                - Flash screen depending ``flash_screen`` parameter.
-                - Cutting text into line to stay within the dialog box
-                  frame.
-                - Writing paragraph by paragraph.
-                - Writing each line of the current paragraph.
-                - Writing each word of line and execute callbacks between.
-                - Waits until a key contained in the class attribute
-                  ``confirm_keys`` was pressed before writing the
-                  following paragraph.
-                - Complete cleaning ``win``.
-
-        .. WARNING::
-=======
+
+            * the current instance (``self``).
+            * the word previously written.
+
         .. note::
             See implementation for more informations on method flow.
 
         .. note::
->>>>>>> 817377f (DialogBox.char_by_char and word_by_word nows return given text argument, start to improve doc.)
             If the volume of text displayed is too large to be contained
             in a dialog box, text will be automatically cut into
             paragraphs using ``textwrap.wrap`` function. See
@@ -327,13 +274,13 @@ def _display_end_indicator(self,
                                    curses.A_BOLD,
                                    curses.A_BLINK)):
         """Displays an end indicator in the lower right corner of
-        textbox.
+        text box.
 
         :param win: ``curses`` window object on which the method
             will have effect.
 
-        :param text_attr: Text attributes of
-            ``end_indicator`` method. This defaults to
+        :param text_attr: Text attributes used to display
+            ``end_indicator``. This defaults to
             ``(curses.A_BOLD, curses.A_BLINK)``.
         """
         if self.end_indicator_char:

visualdialog/error.py

@@ -3,26 +3,27 @@
 
 __all__ = ["PanicError", "ValueNotInBound"]
 
-from typing import Callable
-
 from .type import CursesKey
 
 
 class ValueNotInBound(ValueError):
-    """Exception thrown when incorrect values are passed as parameters
-    to the :class:`BaseTextBox` constructor.
+    """Base ``ValueError``.
+
+    Exception thrown when incorrect values are passed as parameters
+    to the :class:`visualdialog.box.BaseTextBox` constructor.
     """
     pass
 
 
 class PanicError(KeyboardInterrupt):
-    """Exception thrown when a key contained in
-    :class:`BaseTextBox.panic_keys` is pressed.
+    """Base ``KeyboardInterrupt``.
+
+    Exception thrown when a key contained in
+    :attr:`visualdialog.box.BaseTextBox.panic_keys` is pressed.
 
     :param key: Key pressed that caused the exception to be thrown.
     """
-    def __init__(self,
-                 key: CursesKey):
+    def __init__(self, key: CursesKey):
         self.key = key
 
     def __str__(self) -> str: