layout docs

docs/guide/devtools.md

@@ -30,13 +30,13 @@ textual run my_app.py:alternative_app
 
 When running any terminal application, you can no longer use `print` when debugging (or log to the console). This is because anything you write to standard output would overwrite application content, making it unreadable. Fortunately Textual supplies a debug console of its own which has some super helpful features.
 
-To use the console, open up 2 terminal emulators. In the first one, run the following:
+To use the console, open up 2 terminal emulators. Run the following in one of the terminals:
 
 ```bash
 textual console
 ```
 
-This should look something like the following:
+You should see the Textual devtools welcome message:
 
 ```{.textual title="textual console" path="docs/examples/getting_started/console.py", press="_,_"}
 ```
@@ -47,5 +47,16 @@ In the other console, run your application using `textual run` and the `--dev` s
 textual run --dev my_app.py
 ```
 
-Anything you `print` from your application will be displayed in the console window. You can also call the [`log()`][textual.message_pump.MessagePump.log] method on App and Widget objects for advanced formatting. Try it with `self.log(self.tree)`.
+Anything you `print` from your application will be displayed in the console window.
+
+### Textual log
+
+In addition to printing strings, Textual console supports more advanced formatting in logs. To write advanced logs import `log` from `textual` as follows:
+
+```python
+from textual import log
+```
+
+You can logs strings, other Python data types which will be pretty printed in the console. You can also log [Rich renderables](https://rich.readthedocs.io/en/stable/protocol.html). 
+
 

docs/guide/layout.md

@@ -0,0 +1,56 @@
+# Layout
+
+TODO: Explanation of layout
+
+## Vertical layout
+
+<div class="excalidraw">
+--8<-- "docs/images/layout_vertical.excalidraw.svg"
+</div>
+
+
+TODO: Explanation of vertical layout
+
+
+## Horizontal layout
+
+<div class="excalidraw">
+--8<-- "docs/images/layout_horizontal.excalidraw.svg"
+</div>
+
+
+TODO: Explantion of horizontal layout
+
+## Center layout
+
+<div class="excalidraw">
+--8<-- "docs/images/layout_center.excalidraw.svg"
+</div>
+
+
+TODO: Explanation of center layout
+
+## Table layout
+
+
+<div class="excalidraw">
+--8<-- "docs/images/layout_table.excalidraw.svg"
+</div>
+
+
+TODO: Explanation of table layout
+
+
+## Dock
+
+TODO: Diagram
+TODO: Explanation of dock
+
+## Offsets
+
+TODO: Diagram
+TODO: Offsets
+
+## Box Model
+
+TBC

docs/how-to/animation.md

@@ -0,0 +1 @@
+# Animation

docs/how-to/mouse-and-keyboard.md

@@ -0,0 +1 @@
+# Mouse and Keyboard

docs/how-to/scroll.md

@@ -0,0 +1 @@
+# Scroll

docs/index.md

@@ -70,7 +70,5 @@ Textual is a framework for building applications that run within your terminal.
 
 === "Example 2"
 
-    ```{.textual path="docs/examples/introduction/timers.py"}
 
-    ```
 

mkdocs.yml

@@ -7,9 +7,13 @@ nav:
   - "introduction.md"
   - Guide:
     - "guide/devtools.md"
+    - "guide/layout.md"
     - "guide/CSS.md"
     - "guide/events.md"
-
+  - How to:
+    - "how-to/animation.md"
+    - "how-to/mouse-and-keyboard.md"
+    - "how-to/scroll.md"
   - "actions.md"
   - Events:
     - "events/blur.md"

src/textual/_doc.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import runpy
 import os
 from typing import cast, TYPE_CHECKING
 
@@ -11,36 +12,36 @@ if TYPE_CHECKING:
 def format_svg(source, language, css_class, options, md, attrs, **kwargs) -> str:
     """A superfences formatter to insert a SVG screenshot."""
 
-    path: str = attrs["path"]
-    _press = attrs.get("press", None)
-    press = [*_press.split(",")] if _press else ["_"]
-    title = attrs.get("title")
-
-    os.environ["COLUMNS"] = attrs.get("columns", "80")
-    os.environ["LINES"] = attrs.get("lines", "24")
-
-    print(f"screenshotting {path!r}")
-
-    cwd = os.getcwd()
-    examples_path, filename = os.path.split(path)
     try:
-        os.chdir(examples_path)
-        with open(filename, "rt") as python_code:
-            source = python_code.read()
-        app_vars: dict[str, object] = {}
-        exec(source, app_vars)
+        path: str = attrs["path"]
+        _press = attrs.get("press", None)
+        press = [*_press.split(",")] if _press else ["_"]
+        title = attrs.get("title")
 
-        app: App = cast("App", app_vars["app"])
-        app.run(
-            quit_after=5,
-            press=press or ["ctrl+c"],
-            headless=True,
-            screenshot=True,
-            screenshot_title=title,
-        )
-        svg = app._screenshot
-    finally:
-        os.chdir(cwd)
+        os.environ["COLUMNS"] = attrs.get("columns", "80")
+        os.environ["LINES"] = attrs.get("lines", "24")
 
-    assert svg is not None
-    return svg
+        print(f"screenshotting {path!r}")
+
+        cwd = os.getcwd()
+        try:
+            app_vars = runpy.run_path(path)
+            app: App = cast("App", app_vars["app"])
+            app.run(
+                quit_after=5,
+                press=press or ["ctrl+c"],
+                headless=True,
+                screenshot=True,
+                screenshot_title=title,
+            )
+            svg = app._screenshot
+        finally:
+            os.chdir(cwd)
+
+        assert svg is not None
+        return svg
+
+    except Exception as error:
+        import traceback
+
+        traceback.print_exception(error)

src/textual/message_pump.py

@@ -112,6 +112,11 @@ class MessagePump(metaclass=MessagePumpMeta):
 
     @property
     def log(self) -> Logger:
+        """Get a logger for this object.
+
+        Returns:
+            Logger: A logger.
+        """
         return self.app._logger
 
     def _attach(self, parent: MessagePump) -> None: