Docs tidy after dropping dependencies #195
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Barecheck - Code coverage reportTotal: 94.54%Your code coverage diff: 0.01% ▴ Uncovered files and lines |
rwb27
force-pushed
the
docs-tidy-after-dropping-dependencies
branch
from
e915ef8 to
c9bfd2e
Compare
1 task
:deco: now correctly formats cross-references as `@whatever` in the docs.
Contributor
There was a bad indent in the properties module level docstring, and a few imports that confused Sphinx when making cross-references. I've moved an exception and tweaked the way Thing._thing_server_interface is declared to improve the docs: this should not change any code.
ThingServerInterface is used as a type hint for `Thing._thing_server_interface`. It was previously imported with an `if TYPE_CHECKING` guard, but as I've now explicitly type hinted and documented that attribute, any time `get_type_hints` is called on a `Thing` subclass (which is every time one is defined) it will cause an error. I've now imported it unconditionally, which fixes the problem. This does not cause any interdependency issues, as `thing_server_interface` has few onward dependencies.
This shouldn't be duplicated in `conf.py`.
I've converted quite a few links to other pages in the docs, now that they exist. I think redirecting people to the WoT page all the time is causing confusion.
This was left-over old syntax that didn't get migrated.
The "running LabThings" page in the tutorial didn't mention that it was possible to start a ThingServer from within Python. I have now mentioned this on that page, with a link to an example.
rwb27
force-pushed
the
docs-tidy-after-dropping-dependencies
branch
from
0cf53bb to
ed2e66f
Compare
Collaborator
Author
| # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information | ||
|
|
||
| project = "labthings-fastapi" | ||
| copyright = "2024, Richard Bowman" |
Contributor
There was a problem hiding this comment.
Suggested change
| copyright = "2024, Richard Bowman" | |
| copyright = "2025, Richard Bowman" |
julianstirling
approved these changes
Nov 15, 2025
Contributor
julianstirling
left a comment
julianstirling
left a comment
There was a problem hiding this comment.
A couple of teeny things and a suggested date update.
| ------- | ||
|
|
||
| OpenAPI_ is a standard way to describe an HTTP interface. It lists all of the possible HTTP requests that may be made, along with a description of each one, and a description of the possible responses. | ||
| `OpenAPI <https://www.openapis.org/>` is a standard way to describe an HTTP interface. It lists all of the possible HTTP requests that may be made, along with a description of each one, and a description of the possible responses. |
Contributor
There was a problem hiding this comment.
Is it worth adding something to the effect that the OpenAPI docs for any LabThings fastapi server will be hosted at blahblah/docs.
| Descriptors are a way to intercept attribute access on an object. By default, attributes of an object are just variables - so an object called ``foo`` might have an attribute called ``bar``, and you may read its value with ``foo.bar``, write its value with ``foo.bar = "baz"``, and delete the attribute with ``del foo.bar``. If ``foo`` is a descriptor, Python will call the ``__get__`` method of that descriptor when it's read and the ``__set__`` method when it's written to. You have quite probably used a descriptor already, because the built-in `~builtins.property` creates a descriptor object: that's what runs your getter method when the property is accessed. The descriptor protocol is described with plenty of examples in the `Descriptor Guide`_ in the Python documentation. | ||
|
|
||
| In LabThings-FastAPI, descriptors are used to implement :ref:`wot_actions` and :ref:`wot_properties` on `.Thing` subclasses. The intention is that these will function like standard Python methods and properties, but will also be available over HTTP, along with automatic documentation in the :ref:`wot_td` and OpenAPI documents. | ||
| In LabThings-FastAPI, descriptors are used to implement :ref:`actions` and :ref:`properties` on `.Thing` subclasses. The intention is that these will function like standard Python methods and properties, but will also be available over HTTP, along with :ref:`gen_docs`. |
Contributor
There was a problem hiding this comment.
I'd probably need to see it in context in the docs, but probably worth making a note that no one except someone developing LabThings should need to understand descriptors so mentioning them should be reserved for developer docs
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This fixes a few issues with the documentation, mostly minor formatting stuff. It also adds a new docs tool that enables
:deco:to put the@in front of decorators.This follows on from #194 and should be reviewed after that one is merged - currently this looks like there are a lot more changes than there really are!