From ae513e8e10bef6e414c398c31dbe877822142a92 Mon Sep 17 00:00:00 2001 From: Will McGugan Date: Mon, 26 Sep 2022 11:07:27 +0100 Subject: [PATCH] polish docs --- docs/getting_started.md | 2 +- docs/tutorial.md | 10 ++++------ 2 files changed, 5 insertions(+), 7 deletions(-) diff --git a/docs/getting_started.md b/docs/getting_started.md index c2a4f3dab..2ea567083 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -25,7 +25,7 @@ You can install Textual via PyPI. If you plan on developing Textual apps, then you should install `textual[dev]`. The `[dev]` part installs a few extra dependencies for development. ```bash -pip install textual[dev] +pip install "textual[dev]" ``` If you only plan on _running_ Textual apps, then you can drop the `[dev]` part: diff --git a/docs/tutorial.md b/docs/tutorial.md index bf10cd759..e0822b1e9 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -75,7 +75,7 @@ Return types follow `->`. So `-> str:` indicates this method returns a string. ## The App class -The first step in building a Textual app is to import and extend the `App` class. Here's our basic app class with a few methods we will cover below. +The first step in building a Textual app is to import and extend the `App` class. Here's a basic app class we will use as a starting point for the stopwatch app. ```python title="stopwatch01.py" --8<-- "docs/examples/tutorial/stopwatch01.py" @@ -114,9 +114,9 @@ The App class is where most of the logic of Textual apps is written. It is respo Here's what the above app defines: -- `BINDINGS` is a list of tuples that maps (or *binds*) keys to actions in your app. The first value in the tuple is the key; the second value is the name of the action; the final value is a short description. The name of the action (`"toggle_dark"`) is mapped on to the `"action_toggle_dark"` method (see below) which is called when you hit the ++d++ key. +- `BINDINGS` is a list of tuples that maps (or *binds*) keys to actions in your app. The first value in the tuple is the key; the second value is the name of the action; the final value is a short description. We have a single binding which maps the ++d++ key on to the "toggle_dark" action. -- `compose()` is where we construct a user interface with widgets. The `compose()` method may return a list of widgets, but it is generally easier to _yield_ them (making this method a generator). In the example code we yield instances of the widget classes we imported, i.e. the header and the footer. +- `compose()` is where we construct a user interface with widgets. The `compose()` method may return a list of widgets, but it is generally easier to _yield_ them (making this method a generator). In the example code we yield an instance of each of the widget classes we imported, i.e. `Header()` and `Footer()`. - `action_toggle_dark()` defines an _action_ method. Actions are methods beginning with `action_` followed by the name of the action. The `BINDINGS` list above tells Textual to run this action when the user hits the ++d++ key. @@ -124,9 +124,7 @@ Here's what the above app defines: --8<-- "docs/examples/tutorial/stopwatch01.py" ``` -The final three lines create an instance of the app and call [run()][textual.app.App.run] method within a `__name__ == "__main__"` block. This is so we can call `python stopwatch01.py` to run the app, or we could import `stopwatch01` as part of a larger application. - -It's the run method that puts the terminal in to *application mode* so that Textual can take over updating the terminal and handling keyboard and mouse input. +The final three lines create an instance of the app and call [run()][textual.app.App.run] which puts your terminal in to *application mode* and runs the app until you exit with ++ctrl+c++. This happens within a `__name__ == "__main__"` block so we could run the app with `python stopwatch01.py` or import it as part of a larger project. ## Designing a UI with widgets