docs: TUI (#21)

* tui docs * docs
FBruzzesi · Jun 10, 2024 · 179fe21 · 179fe21
1 parent 8c79747
commit 179fe21
Show file tree

Hide file tree

Showing 8 changed files with 101 additions and 42 deletions.
diff --git a/README.md b/README.md
@@ -6,21 +6,36 @@ Scikit-learn smithy is a tool that helps you to forge scikit-learn compatible es
 
 ---
 
-[Documentation](https://fbruzzesi.github.io/sklearn-smithy) | [Repository](https://github.com/fbruzzesi/sklearn-smithy) | [Issue Tracker](https://github.com/fbruzzesi/sklearn-smithy/issues)
+[WebUI](https://sklearn-smithy.streamlit.app/) | [Documentation](https://fbruzzesi.github.io/sklearn-smithy) | [Repository](https://github.com/fbruzzesi/sklearn-smithy) | [Issue Tracker](https://github.com/fbruzzesi/sklearn-smithy/issues)
 
 ---
 
 How can you use it?
 
-✅ Directly from the web: we have a [web UI](https://sklearn-smithy.streamlit.app/) powered by [streamlit](https://streamlit.io/).
+<details><summary>✅ Directly from the browser via our [web UI](https://sklearn-smithy.streamlit.app/). </summary>
 
-✅ As a CLI (command line interface) in your terminal (requires [installation](#installation)) powered by [typer](https://typer.tiangolo.com/):
+- It requires no installation.
+- Powered by [streamlit](https://streamlit.io/)
 
-```terminal
-smith forge
-```
+<img src="https://raw.githubusercontent.com/FBruzzesi/sklearn-smithy/main/docs/img/webui.png" align="right">
+
+</details>
+
+<details><summary>✅ As a CLI (command line interface) in your terminal via the `smith forge` command.</summary>
+
+- It requires [installation](#installation).
+- Powered by [typer](https://typer.tiangolo.com/).
+
+</details>
+
+<details><summary>✅ As a TUI (terminal user interface) in your terminal via the `smith-tui` command.</summary>
+
+- It requires installing [extra dependencies](#extra-dependencies).
+- Powered by [textual](https://textual.textualize.io/), using the `smith-tui` command.
 
-🚧 As a TUI (terminal user interface): Work in progress!
+<img src="https://raw.githubusercontent.com/FBruzzesi/sklearn-smithy/main/docs/img/tui.png" align="right">
+
+</details>
 
 All these tools will prompt a series of questions regarding the estimator you want to create, and then it will generate the boilerplate code for you.
 
@@ -70,12 +85,13 @@ Scikit-learn documentation on how to
 
 The following types of scikit-learn estimator are supported:
 
-- Classifier
-- Regressor
-- Transformer
-  - Feature Selector
-- Outlier Detector
-- Clusterer
+- ✅ Classifier
+- ✅ Regressor
+- ✅ Outlier Detector
+- ✅ Clusterer
+- ✅ Transformer
+  - ✅ Feature Selector
+- 🚧 Meta Estimator
 
 ## Installation
 
@@ -85,7 +101,7 @@ sklearn-smithy is available on [pypi](https://pypi.org/project/sklearn-smithy),
 python -m pip install sklearn-smithy
 ```
 
-**Remark:** The minimum Python version supported is 3.10.
+**Remark:** The minimum Python version required is 3.10.
 
 This will make the `smith` command available in your terminal, and you should be able to run the following:
 
@@ -95,6 +111,14 @@ smith version
 
 > sklearn-smithy=...
 
+### Extra dependencies
+
+To run the TUI, you need to install the `textual` dependency as well:
+
+```bash
+python -m pip install "sklearn-smithy[textual]"
+```
+
 ## User guide 📚
 
 Please refer to the dedicated [user guide](https://fbruzzesi.github.io/sklearn-smithy/user-guide/) documentation section.

diff --git a/docs/img/tui.png b/docs/img/tui.png
diff --git a/docs/img/webui.png b/docs/img/webui.png
diff --git a/docs/index.md b/docs/index.md
@@ -6,27 +6,25 @@ Scikit-learn smithy is a tool that helps you to forge scikit-learn compatible es
 
 How can you use it?
 
-- [x] Directly from the web: we have a [web UI](https://sklearn-smithy.streamlit.app/){:target="_blank"} powered by [streamlit](https://streamlit.io/){:target="_blank"}.
-- [x] As a CLI (command line interface) in your terminal (requires [installation](installation.md)) powered by [typer](https://typer.tiangolo.com/){:target="_blank"}:
+- [x] Directly from the browser via our [web UI](https://sklearn-smithy.streamlit.app/){:target="_blank"} ([more info](user-guide.md/#web-ui)).  
+- [x] As a CLI (command line interface) in your terminal via the `smith forge` command ([more info](user-guide.md/#cli))
+- [x] As a TUI (terminal user interface) in your terminal via the `smith-tui` command ([more info](user-guide.md/#tui))
 
-    ```terminal
-    smith forge
-    ```
-
-- [ ] As a TUI (terminal user interface): [Work in progress](https://github.com/FBruzzesi/sklearn-smithy/issues/1)!
-
-All these tools will prompt a series of questions regarding the estimator you want to create, and then it will generate the boilerplate code for you.
+!!! info
+
+    All these tools will prompt a series of questions regarding the estimator you want to create, and then it will generate the boilerplate code for you.
 
 ## Supported estimators
 
 The following types of scikit-learn estimator are supported:
 
-- Classifier
-- Regressor
-- Transformer
-  - Feature Selector
-- Outlier Detector
-- Clusterer
+- [x] Classifier
+- [x] Regressor
+- [x] Outlier Detector
+- [x] Clusterer
+- [x] Transformer
+    - [x] Feature Selector
+- [ ] Meta Estimator
 
 ## Origin story
 

diff --git a/docs/installation.md b/docs/installation.md
@@ -7,7 +7,7 @@ python -m pip install sklearn-smithy
 ```
 
 !!! warning
-    The minimum Python version supported is 3.10.
+    The minimum Python version required is 3.10.
 
 This will make the `smith` command available in your terminal, and you should be able to run the following:
 
@@ -17,6 +17,14 @@ smith version
 
 > sklearn-smithy=...
 
+## Extra dependencies
+
+To run the TUI, you need to install the `textual` dependency as well:
+
+```bash
+python -m pip install "sklearn-smithy[textual]"
+```
+
 ## Other installation methods
 
 === "pip + source/git"

diff --git a/docs/user-guide.md b/docs/user-guide.md
@@ -6,20 +6,37 @@ Let's see how to use each one of them.
 
 ## Web UI 🌐
 
-The web UI is available at [sklearn-smithy.streamlit.app](https://sklearn-smithy.streamlit.app/){:target="_blank"} allowing you to interact with the tool directly from your browser.
+TL;DR:
 
-This option does not require any installation, and it is the most user-friendly way to use the tool if you have access to a browser or do not want to install anything on your machine.
+- [x] Available at [sklearn-smithy.streamlit.app](https://sklearn-smithy.streamlit.app/){:target="_blank"}
+- [x] It requires no installation.
+- [x] Powered by [streamlit](https://streamlit.io/){:target="_blank"}
+
+The web UI is the most user-friendly, low barrier way, to interact with the tool by accessing it directly from your browser, without any installation required.
+
+Once the estimator is forged, you can download the script with the code as a `.py` file, or you can copy the code directly from the browser.
+
+??? example "Screenshot"
+    ![Web UI](img/webui.png)
 
 ## CLI ⌨️
 
+TL;DR:
+
+- [x] Available via the `smith forge` command.
+- [x] It requires [installation](installation.md): `python -m pip install sklearn-smithy`
+- [x] Powered by [typer](https://typer.tiangolo.com/).
+
 Once the library is installed, the `smith` CLI (Command Line Interface) will be available and that is the primary way to interact with the `smithy` package.
 
 The CLI provides a main command called `forge`, which will prompt a series of question in the terminal, based on which it will generate the code for the estimator.
 
 !!! warning "Non-interactive mode"
-    As any CLI, in principle it would be possible to run it in a non-interactive way, however this is not *fully* supported yet and it comes with some risks and limitations.
+    As for any CLI, in principle it would be possible to run it in a non-interactive way, however this is not *fully* supported yet and it comes with some risks and limitations.
 
-    The reason for this is that the validation and the parameters interaction happen while prompting the questions one after the other, meaning that the input to one prompt will follow next.
+    The reason for this is that the validation and the parameters interaction happen while prompting the questions *one after the other*, meaning that the input to one prompt will determine what follows next.
+
+### `smith forge` example
 
 Let's see an example of how to use `smith forge` command:
 
@@ -60,4 +77,18 @@ from sklearn.utils.validation import check_is_fitted, check_array
 
 ## TUI 💻
 
-🚧 WIP
+TL;DR:
+
+- [x] Available via the `smith-tui` command.
+- [x] It requires installing [extra dependencies](installation.md#extra-dependencies): `python -m pip install "sklearn-smithy[textual]"`
+- [x] Powered by [textual](https://textual.textualize.io/).
+
+If you like the CLI, but prefer a more interactive and graphical way from the comfort of your terminal, you can use the TUI (Terminal User Interface) provided by the `smith-tui` command.
+
+??? example "Screenshot"
+
+    ```console
+    $ smith-tui
+    ```
+
+    ![TUI](img/tui.png)
diff --git a/sksmithy/tui/_tui.py b/sksmithy/tui/_tui.py
@@ -32,7 +32,7 @@ class ForgeTUI(App):
     """Textual app to forge scikit-learn compatible estimators."""
 
     CSS_PATH: ClassVar[str] = str(resources.files("sksmithy") / "_static" / "tui.tcss")
-    TITLE: ClassVar[str] = "Smithy Forge"  # type: ignore[misc]
+    TITLE: ClassVar[str] = "Scikit-learn Smithy ⚒️"  # type: ignore[misc]
 
     BINDINGS: ClassVar = [
         ("ctrl+d", "toggle_sidebar", "Description"),
@@ -46,14 +46,14 @@ class ForgeTUI(App):
     def on_mount(self: Self) -> None:
         """Compose on mount.
 
-        Q: is this needed?
+        Q: is this needed???
         """
         self.compose()
 
     def compose(self: Self) -> ComposeResult:
         """Create child widgets for the app."""
         yield Container(
-            Header(icon="⚒️"),
+            Header(),
             ScrollableContainer(
                 Horizontal(Name(), Estimator()),
                 Horizontal(Required(), Optional()),

diff --git a/tests/test_tui.py b/tests/test_tui.py
@@ -143,11 +143,9 @@ async def test_forge_raise() -> None:
 
 
 @pytest.mark.parametrize("use_binding", [True, False])
-async def test_forge(tmp_path: Path, use_binding: bool) -> None:
+async def test_forge(tmp_path: Path, name: str, estimator: EstimatorType, use_binding: bool) -> None:
     """Test forge button and all of its interactions."""
     app = ForgeTUI()
-    name = "MightyEstimator"
-    estimator = "classifier"
     async with app.run_test(size=None) as pilot:
         name_comp = pilot.app.query_one("#name", Input)
         estimator_comp = pilot.app.query_one("#estimator", Select)
@@ -156,7 +154,7 @@ async def test_forge(tmp_path: Path, use_binding: bool) -> None:
         output_file_comp = pilot.app.query_one("#output-file", Input)
 
         name_comp.value = name
-        estimator_comp.value = estimator
+        estimator_comp.value = estimator.value
 
         await pilot.pause()