Quick start guide throws errors in blank environment

[julianstirling]

Describe the bug
Trying to follow the ReadTheDocs quick start guide and I get errors

To Reproduce

1. Create new environment
2. follow instructions in guide

Expected behaviour

Crashes as:

1. Crashes missing package - pip install labthings-fastapi doesn't install fastapi you need to run pip install labthings-fastapi[server]
2. Once fixed, crashes again with missing package - After this is uvicorn is never installed
3. Once fixed, crashes again in wrong environment - uvicorn counter:app --reload doesn't necessarily run uvicorn from the activated environment. Can be fixed by running python -m uvicorn counter:app --reload
4. Once fixed crashes due to missing module - from labthings_fastapi.thing_server import ThingServer should be from labthings_fastapi.server import ThingServer
5. Once fixed crashes as attribute "app" is not found. Need to add app = server.app as final line

Suggested fix

Create an GitHub action that does exactly the steps of the demo only and check that it runs successfully.

System:

• OS: Ubuntu 24.04
• Python version 3.10
• Version 0.0.7

[rwb27]

I've updated the example (which, as you point out, was out of date in several places) and added a unit test that checks the example file successfully starts a server.

I've not created a new empty environment and checked the install instructions - it would be fairly simple to add a CI job to install in a clean environment, but testing the example code would need some thought: the example will run until stopped with a SIGINT, so it's not as easy as just checking the exit code.

I'm very happy to be told what best practice is regarding checking the package installs OK. Having the CI test an install from PyPI seems odd, as that will not be the version of the code that should be tested - and testing the current version will mean the command differs from what's in the quickstart page. Checking it works if you don't specify the [dev] optional dependency probably is a good idea though...

I'm realising that my move to using configuration files, where you specify the Thing classes with entry point syntax doesn't play well with single file examples. By and large I think that's a helpful thing (it encourages people to write installable Python modules rather than single file scripts), but it does make example code a bit less self-contained. I toyed with adding a command line flag to include the current directory as a module search folder - but I think it might be worth more thought before assuming that's a good idea...

[julianstirling]

Thanks, I'll check through it today.

As a "ideas for the future" not a "we should try this now" thought. Can we start Docker containers within the CI containers? Because if so we could make a quick-start server and spin it up and then kill it, by closing the container. Not sure if this would help.

[rwb27]

This arrived at an opportune moment, so I think I've got it working just with some bash scripting. It's not wonderfully elegant but it does the job. Docker-within-docker is a thing that can be done, but it's much more heavyweight than we need for this.

The issue with examples that aren't importable still needs some thought. Making them all proper packages feels like it would make the examples needlessly complicated, but perhaps it's better than whatever hack would be needed to work with single files.

[rwb27]

Closed by #95