Docs: Specify dependencies for example apps

[bryophyta]

First I just wanted to say that I really like the way that the new docs are taking shape! And I really like the inclusion of some example apps with instructions on how to run them.

The issue I wanted to raise is about how the dependencies for the examples are documented. The Examples section of Getting Started seems to imply that if you follow the steps in that section then you'll be able to run the examples. However, there's a dependency on textual and for some (e.g. dictionary.py) on httpx, too. So the code samples will only run if the user either has textual installed globally, or else is in an activated virtual environment which has it installed.

To my mind, there are two likely user journeys for this section, both of which might run into some trouble:

1. Relative newcomers to python

The current assumption seems to be that users will have a global install of textual because they will have run pip install "textual[dev]" or pip install textual after reading the 'Installation' section earlier on the page.

I can see an argument for not getting into the weeds of virtual environments, in order to keep things as approachable as possible. But to my mind the way that the section is written doesn't make it clear that Examples depends on Installation. (Contrast the 'Demo' section, which begins, Once you have Textual installed....)

2. More experienced python developers

More experienced devs are (I think) unlikely to run the global install command when reading the Installation section. Because the Examples section started with cloning the textual repo, my personal assumption was that we'd create a new virtual environment for the project, which would have the dependencies needed to run the examples.

The natural options in my mind are either:

1. The examples can be run from the project's own dependencies, as specified in poetry.lock, or
2. Create a new virtual environment for the examples themselves, most likely in the /examples/ directory.

Because httpx isn't in the project dependencies, (1) doesn't seem like the way to go. If (2) is the intended route for readers who aren't running a global install, I wonder whether it would be possible to add a requirements.txt file to the /examples/ dir? (I know that there are arguments against using pip but the requirements.txt pattern is a widely understood convention, and pip is already being recommended in the docs and in the example files themselves.)

tl:dr

I realise that it's difficult to balance the requirements of developers with different levels of background knowledge in docs like this, and am very sympathetic to the need not to over-complicate things. But it feels like a slightly more explicit statement about dependencies in the Examples section, and either a requirements.txt file or a more in-depth README in the /examples/ dir itself, would be useful.

I'm happy to raise a PR, but this feels like something where questions of style and judgement are quite salient, so I thought it would be better to raise an issue first and see what you think.

Thanks!

[willmcgugan]

The examples aren't really a part of Textual. They are code bundled with the repository, to demonstrate features. I don't want to introduce httpx as a dependancy where it is generally not needed.

Adding a requirements.txt in examples is a good idea.

[bryophyta]

Thanks for your response! I agree that the requirements.txt approach feels more appropriate here.

I've raised a quick PR, but not sure if this fits with the way you'd want to approach it, so feel free to reject if not!

I was a bit torn about whether to freeze the actual dependencies as of now, or just have:

# requirements.txt
httpx
textual

I opted for the former but I can see a case for the latter.

[github-actions[bot]]

Don't forget to star the repository!

Follow @textualizeio for Textual updates.