Client docs

Problem to solve

Those writing server code don't really know the API they are writing and then using in other Things

Problem in a bit more detail

There has been some discussion about making clients more compatible with linters/type checkers/language servers. I think as someone who didn't design this framework, however well the underlying concepts are explained it is still going to be hard to mentally mutate actions into clients.

If a static representation of client code is generated it would need to be live generated, during coding with a watchdog process. But trying to open a changing live generated code isn't a great interface

Proposed solution

Note, this is not a simple solution so would be long term

We adjust a simple documentation engine like pdoc (something that takes zero configuration unlike sphinx). We create then a command line utility called something like labthings-doc

labthings-doc serve

Could then start a watchdog process that watches code, and creates statically generated clients in a folder watched by pdoc serve, this way a live website would show documentation. Most importantly we would need some labthings specific, docstring conventions for Things. Pdoc uses :param agument_name: for parameters, I would suggest we create :dep dependency: as an additional syntax. This way:

class FakeThing(Thing):
    @thing_action
    def increment_counter(self, counter: CounterDep, amount:int=1) -> None:
        """Increment the counter on another thing

        :param amount: The amount to increment the counter by

        :dep counter: A dependency of type CounterThing
        """
        counter.increment_counter(amount)

If we could then parse this into:

class FakeThingClient(ThingClient):
    def increment_counter(self, amount:int=1) -> None:
        """Increment the counter on another thing

        :param amount: The amount to increment the counter by

        **Dependencies automatically supplied by LabThings FastAPI**

        * counter: A dependency of type CounterThing
        """

Pdoc with zero further configuration would create:

Start by reviewing the proposed labthings-doc serve entry point, pdoc integration, and the Thing/ThingClient example in the issue. Define how watchdog-generated client documentation and the :dep docstring convention should work; done means a live documentation site can show generated clients with dependency information.