From c47ac4e0aab2df204ae39e9237ddd9a5275ff085 Mon Sep 17 00:00:00 2001 From: Francesco Bruzzesi <42817048+FBruzzesi@users.noreply.github.com> Date: Wed, 26 Jun 2024 12:38:49 +0200 Subject: [PATCH] docs: explain non-interactive mode (#35) --- README.md | 6 ++++++ docs/installation.md | 8 +++++++- docs/user-guide.md | 43 ++++++++++++++++++++++++++++++++++++++----- 3 files changed, 51 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index c18a5ab..b921bc1 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,8 @@ How can you use it?
✅ Directly from the browser via a Web UI. +
+ - Available at [sklearn-smithy.streamlit.app](https://sklearn-smithy.streamlit.app/) - It requires no installation. - Powered by [streamlit](https://streamlit.io/) @@ -24,6 +26,8 @@ How can you use it?
✅ As a CLI (command line interface) in the terminal. +
+ - Available via the `smith forge` command. - It requires [installation](#installation): `python -m pip install sklearn-smithy` - Powered by [typer](https://typer.tiangolo.com/). @@ -34,6 +38,8 @@ How can you use it?
✅ As a TUI (terminal user interface) in the terminal. +
+ - Available via the `smith forge-tui` command. - It requires installing [extra dependencies](#extra-dependencies): `python -m pip install "sklearn-smithy[textual]"` - Powered by [textual](https://textual.textualize.io/). diff --git a/docs/installation.md b/docs/installation.md index 52532f6..df978a4 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -19,12 +19,18 @@ smith version ## Extra dependencies -To run the TUI, you need to install the `textual` dependency as well: +To run the TUI (`smith forge-tui`), you need to install the `textual` dependency as well: ```bash python -m pip install "sklearn-smithy[textual]" ``` +To run the WebUI locally (`smith forge-webui`), you need to install the `streamlit` dependency as well: + +```bash +python -m pip install "sklearn-smithy[streamlit]" +``` + ## Other installation methods === "pip + source/git" diff --git a/docs/user-guide.md b/docs/user-guide.md index 45bddd5..8563c10 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -31,11 +31,6 @@ Once the library is installed, the `smith` CLI (Command Line Interface) will be 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 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 determine what follows next. - ### `smith forge` example Let's see an example of how to use `smith forge` command: @@ -74,6 +69,44 @@ from sklearn.utils.validation import check_is_fitted, check_array +### Non-interactive mode + +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 determine what follows next. + +It is still possible to run the CLI in a non-interactive way, but it is not recommended, as it may lead to unexpected results. + +Let's see an example of how to run the `smith forge` command in a non-interactive way: + +!!! example "Non-interactive mode" + + ```terminal + smith forge \ + --name MyEstimator \ + --estimator-type classifier \ + --required-params "a,b" \ + --optional-params "" \ + --no-sample-weight \ + --no-predict-proba \ + --linear \ + --no-decision-function \ + --tags "binary_only" \ + --output-file path/to/file.py + ``` + +Notice how all arguments must be specified, otherwise they will prompt anyway, which means that the command would be interactive. + +Secondly, there is nothing preventing us to run the command with contradictory arguments at the same time. Operating in such a way can lead to two scenarios: + +1. The result will be correct, however unexpected from a user point of view. + For instance, calling `--estimator-type classifier` with `--linear` and `--decision-function` flags, will not create a `decision_function` method, as `LinearClassifierMixin` already takes care of it. +2. The result will be incorrect, as the arguments are contradictory. + +The first case is not a problematic from a functional point of view, while the second will lead to a broken estimator. + +Our suggestion is to use the CLI always in an interactive way, as it will take care of the proprer arguments interaction. + ## TUI 💻 TL;DR: