more docs

docs/examples/guide/structure.py

@@ -0,0 +1,30 @@
+from datetime import datetime
+
+from textual.app import App
+from textual.widget import Widget
+
+
+class Clock(Widget):
+    """A clock app."""
+
+    CSS = """
+    Clock {
+        content-align: center middle;
+    }
+    """
+
+    def on_mount(self):
+        self.set_interval(1, self.refresh)
+
+    def render(self):
+        return datetime.now().strftime("%c")
+
+
+class ClockApp(App):
+    def compose(self):
+        yield Clock()
+
+
+app = ClockApp()
+if __name__ == "__main__":
+    app.run()

docs/guide/CSS.md

@@ -0,0 +1,5 @@
+# Textual CSS
+
+Textual uses a web-technology known as CSS (Cascading Style Sheets) to apply styles to widgets. If you are already familiar with CSS you will be right at home, but don't worry if you aren't; Textual CSS is far simpler than its web counterpart.
+
+## CSS Basics

docs/guide/devtools.md

@@ -0,0 +1,37 @@
+# Textual Devtools
+
+Textual comes with a command line application of the same name. The `textual` command is a super useful tool that will help you to build apps.
+
+## Run
+
+You can run Textual apps with the `run` subcommand. If you supply a path to a Python file it will load and run the application.
+
+```bash
+textual run my_app.py
+```
+
+The `run` sub-command assumes you have a Application instance called `app` in the global scope of your Python file. If the application is called something different, you can specify it with a colon following the filename:
+
+```
+textual run my_app.py:alternative_app
+```
+
+## Console
+
+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 typically overwrite application content, which generally makes an unreadable mess. Fortunately Textual supplies a debug console of it's own which has some super helpful features.
+
+To use the console, open up 2 console emulators. In the first one, run the following:
+
+```bash
+textual console
+```
+
+In the other console, run your application using `textual run` and the `--dev` switch:
+
+```bash
+textual run my_app.py --dev
+```
+
+You should notice that the console will display information regarding the running application, such as events which are sent.
+
+Anything you `print` from your application will be displayed in the console window. You can also call the `log()` method on App and Widget objects for advanced formatting. Try it with `self.log(self.tree)`.

docs/guide/events.md

@@ -0,0 +1,5 @@
+## Events
+
+<div class="excalidraw">
+--8<-- "docs/images/test.excalidraw.svg"
+</div>

docs/index.md

@@ -2,7 +2,11 @@
 
 Welcome to the [Textual](https://github.com/Textualize/textual) framework documentation. Built with ❤️ by [Textualize.io](https://www.textualize.io)
 
-Textual is a Python framework for building applications that run within your terminal. Known as TUIs (Text User Interfaces), such applications have a multitude of benefits:
+<hr>
+
+Textual is a Python framework for building applications that run within your terminal.
+
+Such text-based applications have a number of benefits:
 
 - **Quick to develop:** Textual is a modern Python API.
 - **Low requirements:** Run Textual apps anywhere with a Python interpreter, even single-board computers.
@@ -20,7 +24,7 @@ Textual TUIs are quick and easy to build with pure Python (not to mention _fun_)
 
 ## Installation
 
-You can install Textual via Pypi.
+You can install Textual via PyPi.
 
 If you plan on developing Textual apps, then you can install `textual[dev]`. The `[dev]` part installs a few extra dependencies for development.
 
@@ -28,7 +32,7 @@ If you plan on developing Textual apps, then you can install `textual[dev]`. The
 pip install textual[dev]
 ```
 
-If you only plan on running Textual apps, then you can drop the `[dev]` part:
+If you only plan on _running_ Textual apps, then you can drop the `[dev]` part:
 
 ```bash
 pip install textual

docs/introduction.md

@@ -54,9 +54,9 @@ The `run` method will put your terminal in to "application mode" which disables
 
 ## Handling Events
 
-Most real-world applications will want to interact with the user in some way. To do this we can make use of _event handler_ methods, which are called in response to things the user does such as pressing keys, moving the mouse, resizing the terminal, etc.
+Most real-world applications will need to interact with the user in some way. To do this we can make use of _event handler_ methods, which are called in response to things the user does such as pressing keys, moving the mouse, resizing the terminal, etc.
 
-Each event type is represented by an event object, which is an instance of a class containing information you may need to respond the the event. For instance, the `Key` event contains the key the user pressed and a `Mouse` event will contain the coordinates of the mouse cursor.
+Each event type is represented by an instance of one of a number of Event objects. These event objects may contain additional information regarding the event. For instance, the `Key` event contains the key the user pressed and a `Mouse` event will contain the coordinates of the mouse cursor.
 
 !!! note
 
@@ -82,17 +82,21 @@ If you hit any of the number keys ++0++-++9++, the background will change color
 
 There are two event handlers in this app. Event handlers start with the text `on_` followed by the name of the event in lower case. Hence `on_mount` is called for the `Mount` event, and `on_key` is called for the `Key` event.
 
+!!! note
+
+    Event class names are transformed to _camel case_ when used in event handlers. So the `MouseMove` event will be handled by a method called `on_mouse_move`.
+
 The first event handler to run is `on_mount`. The `Mount` event is sent to your application immediately after entering application mode.
 
 ```python hl_lines="19 20" title="intro02.py"
 --8<-- "docs/examples/introduction/intro02.py"
 ```
 
-This `on_mount` method sets the `background` attribute of `self.styles` to `"darkblue"` which makes the background blue when the application starts. There are a lot of other style properties which define how your app looks. We will explore those later.
+The above `on_mount` method sets the `background` attribute of `self.styles` to `"darkblue"` which makes the background blue when the application starts. There are a lot of other style properties which define how your app looks. We will explore those later.
 
 !!! note
 
-    You may have noticed there is no function call to repaint the screen in this example. Textual is generally smart enough to refresh the screen automatically.
+    You may have noticed there is no function call to repaint the screen in this example. Textual is smart enough to know when the screen needs to be updated, and will do it automatically.
 
 The second event handler will receive `Key` events whenever you press a key on the keyboard:
 
@@ -104,7 +108,7 @@ This method has an `event` positional argument which will receive the event obje
 
 !!! note
 
-    Every event has a corresponding `Event` object, but Textual knows to only call the event handler with the event object if you have it in the argument list. It does this by inspecting the handler method prior to calling it. So if you don't need the event object, you may leave it out.
+    Every event has a corresponding `Event` object. Textual will call your event handler with an event object only if you have it in the argument list. It does this by inspecting the handler method prior to calling it. So if you don't need the event object, you may leave it out.
 
 ## Widgets
 
@@ -122,13 +126,13 @@ Here's what you will see if you run this code:
 
 ```
 
-This script imports `App` and also the `Widget` class from `textual.widget`. To create a Clock widget we extend from the Widget base class:
+This script imports `App` as before and also the `Widget` class from `textual.widget`. To create a Clock widget we extend from the Widget base class.
 
 ```python title="clock01.py" hl_lines="7 8 9 10 11 12 13"
 --8<-- "docs/examples/introduction/clock01.py"
 ```
 
-Widgets support many of the same events as the Application itself, and can be thought of as mini-applications in their own right. The Clock widget responds to a Mount event which is the first event received when a widget is _mounted_ (added to the App). The code in `Clock.on_mount` sets `styles.content_align` to tuple of `("center", "middle")` which tells Textual to center align its contents. If you size the terminal you should see that the text remains centered.
+Widgets support many of the same events as the Application itself, and can be thought of as mini-applications in their own right. The Clock widget responds to a Mount event which is the first event received when a widget is _mounted_ (added to the App). The mount handler (`Clock.on_mount`) sets `styles.content_align` to `("center", "middle")` which tells Textual to center align its contents horizontally and vertically. If you size the terminal you should see that the text remains centered.
 
 The second line in `on_mount` calls `self.set_interval` which tells Textual to invoke the `self.refresh` method once per second, so our clock remains up-to-date.
 
@@ -168,4 +172,4 @@ More sophisticated apps will likely yield multiple widgets from `compose()`, and
 
 We've seen how Textual apps can respond to events, and how to mount widgets which are like mini-applications in their own right. These are key concepts in Textual which you can use to build more sophisticated apps.
 
-The Guide covers this in much more detail, and describes how arrange widgets on the screen and connect them with the core logic of your application.
+The Guide covers this in much more detail and describes how arrange widgets on the screen and connect them with the core logic of your application.

docs/stylesheets/custom.css

@@ -12,3 +12,11 @@ h3 .doc-heading code {
   font-family: "Roboto Mono", "SFMono-Regular", Consolas, "Courier New", Courier,
     monospace;
 }
+
+body[data-md-color-primary="black"] .excalidraw  svg  {  
+  filter: invert(100%) hue-rotate(180deg);
+}
+
+body[data-md-color-primary="black"] .excalidraw svg rect {
+  fill: transparent;
+}

mkdocs.yml

@@ -6,6 +6,8 @@ nav:
   - "introduction.md"
   - Guide:
     - "guide/guide.md"
+    - "guide/events.md"
+    - "guide/devtools.md"
   - "actions.md"
   - Events:
     - "events/mount.md"