Literate code for docs

[pawamoy]

Didn't want to bother again you on Twitter so here are my result on trying to replicate your example with my Markdown Exec extension.

I add this code block in a Markdown page:

```python exec="1" html="true" source="tabbed-left" tabs="Python|Terminal"
--8<-- "gallery/textual.py"
```

It uses the Snippet extension from PyMdown extensions to add the following snippet:

import os  # markdown-exec: hide

os.environ["TEXTUAL"] = "headless"  # markdown-exec: hide
os.environ["TEXTUAL_SCREENSHOT"] = "0.1"  # markdown-exec: hide
os.environ["COLUMNS"] = "80"  # markdown-exec: hide
os.environ["LINES"] = "24"  # markdown-exec: hide

from textual.app import App, ComposeResult
from textual.widgets import Static

class TextApp(App):
    CSS = """
    Screen {
        background: darkblue;
        color: white;
        layout: vertical;
    }
    Static {
        height: auto;
        padding: 2;
        border: heavy white;
        background: #ffffff 30%;
        content-align: center middle;
    }
    """

    def compose(self) -> ComposeResult:
        yield Static("Hello")
        yield Static("[b]World![/b]")

app = TextApp()

app.run()  # markdown-exec: hide
print(app.export_screenshot())  # markdown-exec: hide

Not released yet, but I implemented a way to hide some lines: it simply hides line which contain markdown-exec: hide (language agnostic).

The result is:

Now if you'd like to adopt Markdown Exec, note that you can avoid repeating the "os" and "export" parts thanks again to the Snippet extension, with two different methods.

First one: include the three snippets at once

```python exec="1" html="true" source="tabbed-left" tabs="Python|Terminal"
--8<-- "gallery/textual_setup.py"
--8<-- "gallery/textual.py"
--8<-- "gallery/textual_screenshot.py"
```

Second one: include the pre/post snippets in the main snippet itself:

--8<-- "gallery/textual_setup.py"

from textual.app import App, ComposeResult
from textual.widgets import Static

class TextApp(App):
    CSS = """
    Screen {
        background: darkblue;
        color: white;
        layout: vertical;
    }
    Static {
        height: auto;
        padding: 2;
        border: heavy white;
        background: #ffffff 30%;
        content-align: center middle;
    }
    """

    def compose(self) -> ComposeResult:
        yield Static("Hello")
        yield Static("[b]World![/b]")

app = TextApp()

--8<-- "gallery/textual_screenshot.py"

---

Of course you probably have more specific needs (like when you pass the lines and colums through attrs), so maybe you're better off writing/using your own special fence 🙂 I'm happy to improve Markdown Exec to suit your needs otherwise 😄

[willmcgugan]

Not keen on that I'm afraid. I'd want those examples to be runable from the command line, and without the --8<-- or markdown-exec: hide which a Textual developer isn't going to need.

The only real issue I have with the code in docs-update is that the markdown is quite verbose.

[pawamoy]

I see 🙂 I hope you can find a way to reduce the verbosity of your Markdown!