DialogBox.char_by_char and word_by_word nows return given text argument, improve doc.

Author: Tim-ats-d

doc/source/conf.py

@@ -55,10 +55,6 @@
     "display_version": True
 }
 
-html_logo = "_static/visual-dialog.png"
-
-latex_logo = "_static/visual-dialog.png"
-
 latex_elements = {
     "pointsize": "12pt"
 }

doc/source/faq.rst

@@ -18,5 +18,5 @@ You can use this behavior to perform multiple tasks while text scrolling.
 I am not satisfied with the behavior of DialogBox, how can I change it?
 -----------------------------------------------------------------------
 
-You can create your own derived class by inheriting from ``BaseTextBox``.
-Additionally, you can override the methods of ``DialogBox``.
+You can create your own derived class by inheriting from :class:`BaseTextBox`.
+Additionally, you can override the methods of :class:`DialogBox`.

doc/source/index.rst

@@ -20,7 +20,7 @@ Welcome to Visual-dialog's documentation
 - Text coloring and formatting.
 - Hackable and configurable.
 
-.. IMPORTANT::
+.. important::
    I recommend that you have some knowledge of Python ``curses`` module in order to use the library to its full potential.
 
    Here several links to learn ``curses``:

doc/source/installation.rst

@@ -6,12 +6,22 @@ Using PIP
 
 Install **Visual-dialog** using ``pip`` (The lib is not yet available on **pypi**):
 
-.. code-block::
+.. code-block:: text
 
   pip install git+git://github.com/Tim-ats-d/Visual-dialog
 
 or update library to the latest version:
 
-.. code-block::
+.. code-block:: text
 
   pip install git+git://github.com/Tim-ats-d/Visual-dialog --upgrade
+
+From source
+-----------
+
+.. code-block:: text
+
+  git clone https://github.com/Tim-ats-d/Visual-dialog.git
+  cd Visual-dialog
+  pip install .
+

doc/source/requirements.rst

@@ -12,9 +12,9 @@ Curses
 **Visual-dialog** works with ``curses`` Python module.
 It is available in the standard **Python** library on **UNIX** but it doesn't work out-of-the-box on **Windows**.
 
-To install ``curses`` on **Windows**, you need ``windows-curses`` module:
+To install ``curses`` on **Windows**, you need `windows-curses <https://pypi.org/project/windows-curses/>`_ module:
 
-.. code-block::
+.. code-block:: text
 
   pip install curses-windows
 
@@ -24,6 +24,6 @@ To build the documentation
 - `Sphinx <https://www.sphinx-doc.org/en/master/usage/installation.html>`_ to generate the documentation of library.
 - `sphinx-rtd-theme <https://pypi.org/project/sphinx-rtd-theme/>`_ used as documentation theme.
 
-.. code-block::
+.. code-block:: text
 
   pip install sphinx sphinx_rtd_theme

doc/source/utils.rst

@@ -1,7 +1,7 @@
 Utils
 =====
 
-.. NOTE::
+.. note::
   A sub-module of **Visual-dialog** (``visualdialog.utils``) contains
   functions and classes used by the private API. The context manager
   ``TextAttr`` is used by the library to manage in a more
@@ -16,5 +16,10 @@ Utils
     visualdialog.function(args)
 
 
-.. automodule:: visualdialog.utils
-    :members:
+.. autoclass:: visualdialog.utils.TextAttr
+
+  .. automethod:: __init__
+
+  .. automethod:: __enter__
+
+  .. automethod:: __exit__

doc/source/visualdialog.rst

@@ -1,22 +1,45 @@
 Text boxes
 ==========
 
-.. IMPORTANT::
-  **Visual-dialog** contains two **modules**: ``visualdialog.box`` and ``visualdialog.dialog``.
-  These two **modules** are both imported when you import ``visualdialog``.
+.. important::
+  This library provides two classes but only :class:`DialogBox` is destined to be instantiated.
 
-  Two **classes** are defined in these modules but only ``DialogBox`` is destined to be instantiated.
-
-TextBox
--------
+BaseTextBox
+-----------
 
 .. autoclass:: visualdialog.box.BaseTextBox
-    :members:
-    :undoc-members:
+
+  .. automethod:: __init__
+
+  The following variables are instance attributes:
+
+  .. autoattribute:: confirm_keys
+
+  The following methods are public:
+
+  .. autoattribute:: position
+
+  .. autoattribute:: dimensions
+
+  .. automethod:: framing_box
+
+  .. automethod:: get_input
 
 DialogBox
 ---------
 
 .. autoclass:: visualdialog.dialog.DialogBox
-    :undoc-members:
-    :members:
+
+  .. automethod:: __init__
+
+  The following methods are public:
+
+  .. automethod:: __repr__
+
+  .. automethod:: __enter__
+
+  .. automethod:: __exit__
+
+  .. automethod:: char_by_char
+
+  .. automethod:: word_by_word

visualdialog/box.py

@@ -5,6 +5,7 @@
 
 import curses
 import curses.textpad
+import functools
 from typing import Callable, List, Literal, Sequence, Tuple, Union
 
 from .error import PanicError, ValueNotInBound
@@ -14,7 +15,7 @@
 
 def value_checker(initializer: Callable) -> Callable:
     """A decorator which ensures that correct values are passed to
-    ``BaseTextBox`` initializer to avoid unexpected behavior.
+    :class:`BaseTextBox` initializer to avoid unexpected behavior.
     """
     def __init__(self,
                  pos_x, pos_y,
@@ -43,7 +44,7 @@ def __init__(self,
 class BaseTextBox:
     """This class provides attributs and methods to manage a text box.
 
-    .. NOTE::
+    .. note::
         This class provides a general API for text boxes, it is not
         intended to be instantiated.
 
@@ -97,6 +98,7 @@ def __init__(
                                    CursesTextAttributes] = curses.A_BOLD,
             downtime_chars: Sequence[str] = (",", ".", ":", ";", "!", "?"),
             downtime_chars_delay: int = 600):
+        """Initializes instance of :class:`BaseTextBox`."""
         self.pos_x, self.pos_y = pos_x, pos_y
         self.height, self.width = height - 1, width - 1
 
@@ -118,34 +120,46 @@ def __init__(
         self.downtime_chars = downtime_chars
         self.downtime_chars_delay = downtime_chars_delay
 
-        #: Keystroke acquisition curses method for BaseTextBox.get_input.
+        #: 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 to a list contains " ".
+        #: This defaults `[" "]`.
         self.confirm_keys: List[CursesKey] = [" "]
-        #: List of accepted key to raise PanicError.
-        #: This defaults to an empty list.
+
         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]:
-        """Return a tuple contains x;y position of ``TextBox``.
+<<<<<<< HEAD
+        """Return a tuple contains x;y position of :class:`BaseTextBox`.
+=======
+        """A property that returns a tuple contains x;y position of
+        :class:`BaseTextBox`.
+>>>>>>> 817377f (DialogBox.char_by_char and word_by_word nows return given text argument, start to improve doc.)
 
         The position represents the x;y coordinates of the top left
         corner of text box.
 
-        :returns: x;y position of ``TextBox``.
+        :returns: x;y position of :class:`BaseTextBox`.
         """
         return self.pos_x, self.pos_y
 
     @property
     def dimensions(self) -> Tuple[int, int]:
-        """Return a tuple contains dimensions of ``TextBox``.
-
-        :returns: Height and width of ``TextBox``.
+<<<<<<< HEAD
+        """Return a tuple contains dimensions of :class:`BaseTextBox`.
+=======
+        """A property that return a tuple contains dimensions of
+        :class:`BaseTextBox`.
+>>>>>>> 817377f (DialogBox.char_by_char and word_by_word nows return given text argument, start to improve doc.)
+
+        :returns: Height and width of :class:`BaseTextBox`.
         """
         return (self.height + 1,
                 self.width + 1 + self.title_offsetting_y)
@@ -181,35 +195,23 @@ def framing_box(self, win: CursesWindow):
         curses.textpad.rectangle(win,
                                  self.pos_y + self.title_offsetting_y,
                                  self.pos_x,
-                                 self.pos_y
-                                 + self.title_offsetting_y
-                                 + self.width,
+                                 (self.pos_y
+                                  + self.title_offsetting_y
+                                  + self.width),
                                  self.pos_x + self.height)
 
     def get_input(self, win: CursesWindow):
         """Block execution as long as a key contained in
         ``self.confirm_keys`` is not detected.
 
         The method of key detection depends on the variable
-        ``self.key_detection_mode``. ``"key"`` will acquire the key as
-        a character and ``"code"`` as a key code. This is default to
-        ``"key"``.
+        ``self.key_detection_mode``.
 
         :param win: ``curses`` window object on which the method will
             have effect.
 
         :raises PanicError: If a key contained in ``self.panic_keys`` is
             pressed.
-
-        .. NOTE::
-            - This method uses ``window.getch`` method from ``curses``
-              module. Please refer to `curses documentation
-              <https://docs.python.org/3/library/curses.html?#curses.window.getch>`_
-              for more informations.
-            - This method uses ``window.getkey`` method from ``curses``
-              module. Please refer to `curses documentation
-              <https://docs.python.org/3/library/curses.html?#curses.window.getkey>`_
-              for more informations.
         """
         curses.flushinp()