From f7ae70e9cba2393a030abbbf36b1cdab00061279 Mon Sep 17 00:00:00 2001
From: Francesco Bruzzesi <42817048+FBruzzesi@users.noreply.github.com>
Date: Mon, 10 Jun 2024 22:00:14 +0200
Subject: [PATCH] docs: Render textual natively (#24)

* docs: Render textual natively

* add textual as docs dep
---
 .github/workflows/deploy-docs.yaml  |  2 +-
 .github/workflows/pull-request.yaml |  2 +-
 .gitignore                          |  3 +++
 Makefile                            |  2 ++
 docs/index.md                       |  2 +-
 docs/user-guide.md                  | 18 ++++++++----------
 mkdocs.yml                          |  6 +++++-
 7 files changed, 21 insertions(+), 14 deletions(-)

diff --git a/.github/workflows/deploy-docs.yaml b/.github/workflows/deploy-docs.yaml
index d246c38..bb9bd8c 100644
--- a/.github/workflows/deploy-docs.yaml
+++ b/.github/workflows/deploy-docs.yaml
@@ -32,5 +32,5 @@ jobs:
 
       - name: Install dependencies and deploy
         run: |
-          uv install mkdocs-material --system
+          uv install mkdocs-material textual --system
           mkdocs gh-deploy --force
diff --git a/.github/workflows/pull-request.yaml b/.github/workflows/pull-request.yaml
index cad0dbf..740144b 100644
--- a/.github/workflows/pull-request.yaml
+++ b/.github/workflows/pull-request.yaml
@@ -61,5 +61,5 @@ jobs:
         run: curl -LsSf https://astral.sh/uv/install.sh | sh
       - name: Install dependencies and check docs can build
         run: |
-          uv pip install mkdocs-material --system
+          uv pip install mkdocs-material textual --system
           mkdocs build -v -s
diff --git a/.gitignore b/.gitignore
index 86d443e..1966568 100644
--- a/.gitignore
+++ b/.gitignore
@@ -160,3 +160,6 @@ cython_debug/
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
+
+# Cache of screenshots used in the docs
+.screenshot_cache
\ No newline at end of file
diff --git a/Makefile b/Makefile
index fc59de6..c5de7c8 100644
--- a/Makefile
+++ b/Makefile
@@ -5,7 +5,9 @@ clean-folders:
 		.pytest_cache */.pytest_cache */**/.pytest_cache \
 		.ruff_cache */.ruff_cache */**/.ruff_cache \
 		.mypy_cache */.mypy_cache */**/.mypy_cache \
+		.screenshot_cache \
 		site build dist htmlcov .coverage .tox
+		
 
 lint:
 	ruff version
diff --git a/docs/index.md b/docs/index.md
index b45c393..53ffda7 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -6,7 +6,7 @@ Scikit-learn smithy is a tool that helps you to forge scikit-learn compatible es
 
 How can you use it?
 
-- [x] Directly from the browser via our [web UI](https://sklearn-smithy.streamlit.app/){:target="_blank"} ([more info](user-guide.md/#web-ui)).  
+- [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))
 
diff --git a/docs/user-guide.md b/docs/user-guide.md
index f54ac36..c3b4b53 100644
--- a/docs/user-guide.md
+++ b/docs/user-guide.md
@@ -25,7 +25,7 @@ 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/).
+- [x] Powered by [typer](https://typer.tiangolo.com/){:target="_blank"}.
 
 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.
 
@@ -64,13 +64,12 @@ Now the estimator template to be filled will be available at the specified path
 <div class="termy">
 
 ```console
-$ cat path/to/file.py
+$ cat path/to/file.py | head -n 5
 import numpy as np
 
 from sklearn.base import BaseEstimator, ClassifierMixin
 from sklearn.utils import check_X_y
 from sklearn.utils.validation import check_is_fitted, check_array
-...
 ```
 
 </div>
@@ -81,14 +80,13 @@ 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/).
+- [x] Powered by [textual](https://textual.textualize.io/){:target="_blank"}.
 
 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
+```
 
-    ```console
-    $ smith-tui
-    ```
-    
-    ![TUI](img/tui.png)
+```{.textual path="sksmithy/tui/_tui.py" columns="127" lines="32"}
+```
diff --git a/mkdocs.yml b/mkdocs.yml
index 1f3f5e4..dae8528 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -69,7 +69,11 @@ markdown_extensions:
       permalink: true
   - pymdownx.inlinehilite
   - pymdownx.snippets
-  - pymdownx.superfences
+  - pymdownx.superfences:
+      custom_fences:
+        - name: textual
+          class: textual
+          format: !!python/name:textual._doc.format_svg
   - pymdownx.details
   - pymdownx.tasklist:
       custom_checkbox: true