Confusing links in generated documentation

Most of the key symbols (e.g. Thing) appear in more than one place in our API, for example labthings_fastapi.Thing and labthings_fastapi.thing.Thing.

Each symbol is properly documented only once, at its intended top-level location (e.g. the proper documentation for Thing is at labthings_fastapi.Thing). However, there are some references to the fully-qualified labthings_fastapi.thing.Thing that end up taking you to that submodule, which has a confusingly skeletal definition of Thing that doesn't link to the main one.

We probably need to manually look through these symbols and ensure that the deeper definitions link properly to the top-level documentation.

In the future, this might be done by not autogenerating the API docs each time, or possibly by having manually structured documentation for the top level labthings_fastapi module and a couple of the user-facing submodules, plus some autogeneration for the rest of the package (which is primarily developer-facing).

I think having a clear split between the API we expect people to use when developing Things and using the library, and the internal API that's mostly for developers, would be very helpful. From what I've read, the preferred way to do this with Sphinx is to have some manual intervention in the API docs. For us, I think the sweet spot is a manually curated set of documentation for the top modules (which absolutely should use autodoc to describe classes and functions - I'm not suggesting it should be entirely manual), plus an autogenerated description of the rest of the API.

Start by inspecting the generated API documentation for labthings_fastapi.Thing and submodule symbols such as labthings_fastapi.thing.Thing, then compare references to their displayed destinations. Review how Sphinx autodoc currently generates these entries. Done means deeper definitions consistently link to the intended top-level documentation and the public-versus-internal API split is documented clearly.