Merge pull request #19 from Helveg/pytest

Reworked documentation and formalize test suite

conftest.py

@@ -0,0 +1,10 @@
+import pytest
+import os
+
+
+@pytest.fixture(autouse=True)
+def skip_if_windows():
+    if os.name == "nt":
+        pytest.exit("Test suite not supported on Windows. Please use WSL.")
+    else:
+        yield

dashing/__init__.py

@@ -7,14 +7,14 @@
 Dashing automatically fills the screen with "tiles".
 
 There are 2 type of "container" tiles that allow vertical and horizontal splitting
-called VSplit and HSplit. Dashing scales them based on the screen size.
+called ``VSplit`` and ``HSplit``. Dashing scales them based on the screen size.
 
-Any tile passed as argument at init time will be nested using the .items attribute
+Any tile passed as argument at init time will be nested using the ``.items`` attribute
 
-.items can be used to access, add or remove nested tiles.
+``.items`` can be used to access, add or remove nested tiles.
 
 You can easily extend Dashing with new tile types. Subclass :class:`Tile`, implement
-__init__ and _display.
+``__init__`` and ``_display``.
 
 The other types of tiles are:
     - :class:`Text` - simple text
@@ -27,11 +27,11 @@
     - :class:`HBrailleChart`
     - :class:`HBrailleFilledChart`
 
-All tiles accept title, color, border_color keywords arguments at init time.
+All tiles accept ``title``, ``color``, ``border_color`` keywords arguments at init time.
 
 Gauges represent an instant value between 0 and 100.
-You can set a value at init time using the val keyword argument or access the
-.value attribute at any time.
+You can set a value at init time using the ``val`` keyword argument or access the
+``.value`` attribute at any time.
 
 Charts represent a sequence of values between 0 and 100 and scroll automatically.
 
@@ -161,16 +161,25 @@ def color(
 
 
 class Tile(object):
-    def __init__(
-        self, title: str = "", border_color: Optional[Color] = None, color: Color = 0
-    ) -> None:
+    """Base class for all Dashing tiles."""
+
+    def __init__(self, title: str = "", border_color: Optional[Color] = None, color: Color = 0) -> None:
+        """
+        :param title: Title of the tile
+        :param border_color: Color of the border. Setting this will enable a border and shrinks available size by 1
+          character on each side.
+        :param color: Color of the text inside the tile.
+        """
         self.title = title
         self.color = color
         self.border_color = border_color
         self._terminal: Optional[Terminal] = None
 
     def _display(self, tbox: TBox, parent: Optional["Tile"]) -> None:
-        """Render current tile"""
+        """
+        Implement this method when subclassing :class:`.Tile`, to fill in the available space outlined by
+        the ``tbox`` with the tile content.
+        """
         raise NotImplementedError
 
     def _draw_borders_and_title(self, tbox: TBox):

docs/.gitignore

@@ -0,0 +1,2 @@
+_build
+_autosummary

docs/_templates/autosummary/module.rst

@@ -0,0 +1,5 @@
+{{ fullname }}
+{{ underline }}
+
+.. automodule:: {{ fullname }}
+    :members:

docs/api.rst

@@ -0,0 +1,7 @@
+API Reference
+=============
+
+.. autosummary::
+   :toctree: _autosummary
+
+    dashing

docs/conf.py

@@ -29,26 +29,29 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ["sphinx.ext.autodoc"]
-
+extensions = ["sphinx.ext.autodoc", "sphinx.ext.autosummary"]
+autosummary_generate = True
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "_templates"]
 
 
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "alabaster"
+html_theme = "furo"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
+
+# Show both the class' docstring, and `__init__` docstring:
+autoclass_content = "both"

docs/developers.rst

@@ -0,0 +1,15 @@
+Development
+-----------
+
+``dashing`` welcomes all contributions.
+
+Testing
+=======
+
+We use ``pytest`` for the test suite, ``pyte`` to emulate a terminal, and ``pexpect`` to spawn a process and communicate
+with the emulated terminal per test. ``pexpect`` does not fully support Windows, so the test suite can only run on WSL
+for Windows users.
+
+You can run the testsuite simply by running::
+
+   pytest

docs/getting_started.rst

@@ -0,0 +1,61 @@
+Getting Started
+===============
+
+Setting up a basic application
+------------------------------
+
+Dashing lets you create elegantly tiled interfaces for your terminal application user interface (TUI). Create your TUI
+by constructing a suitable root :class:`.Tile`. The simplest possible example would be to create a single :class:`.Text` tile:
+
+.. code-block:: python
+
+    from dashing import Text, open_terminal
+
+    ui = Text(text="Hello World, this is dashing!", color=0)
+
+    with open_terminal() as terminal:
+        ui.display(terminal)
+        input("\nPress Enter to quit")
+
+You should see the Dashing TUI open, display the application, wait for input, and then clean itself up.
+
+.. warning::
+
+  We use color ``0``, black, which might not contrast enough with your terminal's color to be visible! Try another number
+  between 0-7 (included) if you don't see anything.
+
+
+.. admonition:: Note - Terminals
+  :class: note
+
+  We use the :func:`.open_terminal` helper to open an underlying Blessed terminal. If you wish to integrate Dashing into
+  an existing Blessed application, you can simply pass an existing ``Terminal`` object. Without using a proper Terminal
+  context, calls to ``ui.display()`` may leave the user's terminal in a messy state!
+
+The power of Dashing shines when you combine it with an event loop, and make periodic calls to ``ui.display()`` to
+update and redraw the screen.
+
+Let's create an application with a title, border, and 2 horizontal gauges that increment decrement for a couple of
+seconds:
+
+
+.. code-block:: python
+
+    from dashing import HGauge, HSplit, Text, open_terminal
+
+    ui = HSplit(
+         HGauge(),
+         HGauge(val=100),
+         border_color=3,
+         title="My First App"
+    )
+
+    with open_terminal() as terminal:
+        for i in range(100):
+            ui.items[0].value = i % 101
+            ui.items[1].value = (100 - (i % 101))
+            ui.display(terminal)
+            time.sleep(1 / 25)
+
+As you can see, Dashing added a border and a title around the root tile, and periodically redraws the screen with the
+new values.

docs/index.rst

@@ -1,11 +1,16 @@
 dashing
 -------
 
-* :ref:`genindex`
-* :ref:`modindex`
+.. toctree::
+   :maxdepth: 2
 
-Overview
-========
+   getting_started
+   developers
+   api
 
-.. automodule:: dashing
-   :members:
+Installation
+============
+
+You can install the package with::
+
+   pip install dashing

pyproject.toml

@@ -24,7 +24,17 @@ dev = [
     "pre-commit~=3.0",
     "isort~=5.12",
     "flake8-pyproject~=1.2",
-    "bump-my-version~=0.18"
+    "bump-my-version~=0.18",
+    "dashing[test,docs]"
+]
+docs = [
+    "sphinx~=7.0",
+    "furo~=2024.1"
+]
+test = [
+    "pytest~=8.0",
+    "pyte~=0.8",
+    "pexpect~=4.9"
 ]
 
 [tool.isort]