From 26a55a27fbcfde94319fc9ef0e4c55a1a2d95cfe Mon Sep 17 00:00:00 2001 From: Robin De Schepper Date: Fri, 22 Mar 2024 12:11:33 +0100 Subject: [PATCH 01/11] specify test deps --- pyproject.toml | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 383b266..fd968ed 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -24,7 +24,13 @@ dev = [ "pre-commit~=3.0", "isort~=5.12", "flake8-pyproject~=1.2", - "bump-my-version~=0.18" + "bump-my-version~=0.18", + "dashing[test]" +] +test = [ + "pytest~=8.0", + "pyte~=0.8", + "pexpect~=4.9" ] [tool.isort] From c6eec7363675a4621000932280ba193a610e2754 Mon Sep 17 00:00:00 2001 From: Robin De Schepper Date: Fri, 22 Mar 2024 12:11:37 +0100 Subject: [PATCH 02/11] abort test suite on windows --- conftest.py | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 conftest.py diff --git a/conftest.py b/conftest.py new file mode 100644 index 0000000..93edf7a --- /dev/null +++ b/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 From f1b69602242ee85d9e70180b25fc868561d9cb37 Mon Sep 17 00:00:00 2001 From: Robin De Schepper Date: Fri, 22 Mar 2024 12:49:16 +0100 Subject: [PATCH 03/11] add dev docs on the test suite --- docs/.gitignore | 1 + docs/_static/.gitkeep | 0 docs/developers.rst | 15 +++++++++++++++ docs/index.rst | 14 +++++++++++++- 4 files changed, 29 insertions(+), 1 deletion(-) create mode 100644 docs/.gitignore create mode 100644 docs/_static/.gitkeep create mode 100644 docs/developers.rst diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..9c5f578 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +_build \ No newline at end of file diff --git a/docs/_static/.gitkeep b/docs/_static/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/developers.rst b/docs/developers.rst new file mode 100644 index 0000000..c9e6643 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 6ab409b..4f0af0e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,11 +1,23 @@ dashing ------- +.. toctree:: + :maxdepth: 2 + + developers + * :ref:`genindex` * :ref:`modindex` +Installation +============ + +You can install the package with:: + + pip install dashing + Overview ======== .. automodule:: dashing - :members: + :members: \ No newline at end of file From 143086ee586a26d764aa6309864fc6d73b6ccb41 Mon Sep 17 00:00:00 2001 From: Robin De Schepper Date: Fri, 22 Mar 2024 14:26:31 +0100 Subject: [PATCH 04/11] add missing backticks --- dashing/__init__.py | 27 +++++++++++++++++++-------- 1 file changed, 19 insertions(+), 8 deletions(-) diff --git a/dashing/__init__.py b/dashing/__init__.py index 59afc40..bfd00d0 100644 --- a/dashing/__init__.py +++ b/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. @@ -88,14 +88,25 @@ class Tile(object): + """Base class for all Dashing tiles.""" + def __init__(self, title: str = None, border_color: Color = None, color: Color = 0): + """ + :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"]): - """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): From 736b65e7b1ac5448f156f6737024022bb2bbc6f4 Mon Sep 17 00:00:00 2001 From: Robin De Schepper Date: Fri, 22 Mar 2024 14:26:46 +0100 Subject: [PATCH 05/11] ignore the autogenerated autosummary directory --- docs/.gitignore | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/.gitignore b/docs/.gitignore index 9c5f578..0aec095 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1 +1,2 @@ -_build \ No newline at end of file +_build +_autosummary \ No newline at end of file From 3801b771b7276186242c7daffb2db2da8caa40b7 Mon Sep 17 00:00:00 2001 From: Robin De Schepper Date: Fri, 22 Mar 2024 14:26:58 +0100 Subject: [PATCH 06/11] switch theme --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index c1a8b8c..35ed320 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -46,7 +46,7 @@ # 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, From 9bd56973ddd1990cae11edcc4430bffa617b3068 Mon Sep 17 00:00:00 2001 From: Robin De Schepper Date: Fri, 22 Mar 2024 14:29:44 +0100 Subject: [PATCH 07/11] add `docs` extras --- pyproject.toml | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index fd968ed..933752c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -25,7 +25,11 @@ dev = [ "isort~=5.12", "flake8-pyproject~=1.2", "bump-my-version~=0.18", - "dashing[test]" + "dashing[test,docs]" +] +docs = [ + "sphinx~=7.0", + "furo~=2024.1" ] test = [ "pytest~=8.0", From 30d211b6a38889c33ef09517cc5389588a0971b1 Mon Sep 17 00:00:00 2001 From: Robin De Schepper Date: Fri, 22 Mar 2024 14:29:59 +0100 Subject: [PATCH 08/11] add an API reference document --- docs/api.rst | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 docs/api.rst diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 0000000..bec1e49 --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,7 @@ +API Reference +============= + +.. autosummary:: + :toctree: _autosummary + + dashing \ No newline at end of file From 3ddf6f70bde2bbd33291efa3ae1c04e73c2675e7 Mon Sep 17 00:00:00 2001 From: Robin De Schepper Date: Fri, 22 Mar 2024 14:30:12 +0100 Subject: [PATCH 09/11] add an automodule template for autosummary --- docs/_templates/autosummary/module.rst | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 docs/_templates/autosummary/module.rst diff --git a/docs/_templates/autosummary/module.rst b/docs/_templates/autosummary/module.rst new file mode 100644 index 0000000..7a16b54 --- /dev/null +++ b/docs/_templates/autosummary/module.rst @@ -0,0 +1,5 @@ +{{ fullname }} +{{ underline }} + +.. automodule:: {{ fullname }} + :members: \ No newline at end of file From b34c5f053628a73812b9c3ad41edf333e73b75c5 Mon Sep 17 00:00:00 2001 From: Robin De Schepper Date: Fri, 22 Mar 2024 14:30:32 +0100 Subject: [PATCH 10/11] configure autosummary --- docs/conf.py | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 35ed320..3fd41d2 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -29,8 +29,8 @@ # 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"] @@ -38,7 +38,7 @@ # 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 ------------------------------------------------- @@ -52,3 +52,6 @@ # 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" From e480ff9b7b29d6663503315bd98e1f7ca77a648a Mon Sep 17 00:00:00 2001 From: Robin De Schepper Date: Fri, 22 Mar 2024 17:06:50 +0100 Subject: [PATCH 11/11] restructured index and added small getting started --- docs/getting_started.rst | 61 ++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 11 ++------ 2 files changed, 63 insertions(+), 9 deletions(-) create mode 100644 docs/getting_started.rst diff --git a/docs/getting_started.rst b/docs/getting_started.rst new file mode 100644 index 0000000..0e03856 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 4f0af0e..ab788c2 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -4,10 +4,9 @@ dashing .. toctree:: :maxdepth: 2 + getting_started developers - -* :ref:`genindex` -* :ref:`modindex` + api Installation ============ @@ -15,9 +14,3 @@ Installation You can install the package with:: pip install dashing - -Overview -======== - -.. automodule:: dashing - :members: \ No newline at end of file