De-emphasise WoT core concepts

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.

Author: rwb27

docs/source/documentation.rst

@@ -3,7 +3,7 @@
 Generated documentation
 =======================
 
-LabThings describes its HTTP API in two ways: with a :ref:`wot_td` and with an OpenAPI_ document.
+LabThings describes its HTTP API in two ways: with a :ref:`gen_td` and with an OpenAPI_ document.
 
 .. _openapi:
 
@@ -17,9 +17,9 @@ OpenAPI
 Thing Description
 -----------------
 
-Each :ref:`wot_thing` is documented by a Thing Description, which is a JSON document describing all of the ways to interact with that Thing (:ref:`wot_affordances`\ ). The WoT_ standard defines the `Thing Description`_ and includes a JSON Schema against which it may be validated.
+Each :ref:`Thing <things>` is documented by a :ref:`gen_td`, which is a JSON document describing all of the ways to interact with that Thing (:ref:`wot_affordances`\ ). The WoT_ standard defines the `Thing Description`_ and includes a JSON Schema against which it may be validated.
 
-Thing Description documents are higher-level than OpenAPI_ and focus on the capabilities of the Thing. For example, they include a list of properties, where each action is described only once. LabThings treats the Thing Description as your public API, and as a general rule anything not described in the Thing Description is not available over HTTP or to a `.DirectThingClient`\ .
+Thing Description documents are higher-level than OpenAPI_ and focus on the capabilities of the Thing. For example, they include a list of properties, where each action is described only once. LabThings treats the Thing Description as your public API, and as a general rule anything not described in the Thing Description is not available over HTTP.
 
 Comparison of Thing Description and OpenAPI
 -------------------------------------------

docs/source/index.rst

@@ -29,7 +29,7 @@ Documentation for LabThings-FastAPI
 * Actions are decorated methods of a `.Thing` class. There is no need for separate schemas or endpoint definitions.
 * Properties are defined either as typed attributes (similar to `pydantic` or `dataclasses`) or with a `property`\ -like decorator.
 * Lifecycle and concurrency are appropriate for hardware: `Thing` code is always run in a thread, and each `Thing` is instantiated, started up, and shut down only once.
-* Vocabulary and concepts are aligned with the `W3C Web of Things <https://www.w3.org/WoT/>`_ standard (see :doc:`wot_core_concepts`)
+* Vocabulary and concepts are aligned with the `W3C Web of Things <https://www.w3.org/WoT/>`_ standard (see :ref:`wot_cc`)
 
 Previous version
 ----------------

docs/source/see_also.rst

@@ -10,7 +10,7 @@ Descriptors
 
 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`.
 
 There are a few useful notes that relate to many of the descriptors in LabThings-FastAPI:
 

docs/source/structure.rst

@@ -20,6 +20,8 @@ LabThings-FastAPI is built on top of `fastapi`\ , which is a fast, modern HTTP f
 * Generating a :ref:`gen_td` in addition to the :ref:`openapi` documentation produced by `fastapi`\ .
 * Making connections between `.Thing` instances as required.
 
+.. _things:
+
 Things
 -----------
 
@@ -46,7 +48,7 @@ The attributes of a `.Thing` are made available over HTTP by decorating or marki
 Client Code
 -----------
 
-Client code can be written in any language that supports an HTTP request. However, LabThings FastAPI provides additional functionality that makes writing client code in Python easier.
+Client code can be written in any language that supports an HTTP request. However, LabThings FastAPI provides additional functionality that makes writing client code in Python easier. See :ref:`using_things` for more detail.
 
 `.ThingClient` is a class that wraps up the required HTTP requests into a simpler interface. It can retrieve the :ref:`gen_td` over HTTP and use it to generate a new object with methods matching each `.thing_action` and properties matching each `.property`.
 

docs/source/tutorial/properties.rst

@@ -1,4 +1,5 @@
 .. _tutorial_properties:
+.. _properties:
 
 Properties
 =========================

docs/source/using_things.rst

@@ -1,12 +1,23 @@
+.. _using_things:
+
 Using Things
 ============
 
 The interface to a `Thing` is defined by its actions, properties and events [#events]_. These can all be accessed remotely via HTTP from any language, but a more convenient interface in Python is a `.ThingClient` subclass. This provides a simple, pythonic interface to the `.Thing`, allowing you to call actions and access properties as if they were methods and attributes of a Python object.
 
 `.ThingClient` subclasses can be generated dynamically from a URL using :meth:`.ThingClient.from_url`. This creates an object with the right methods, properties and docstrings, though type hints are often missing. The client can be "introspected" to explore its methods and properties using tools that work at run-time (e.g. autocompletion in a Jupyter notebook), but "static" analysis tools will not yet work.
 
+Both the input and return types of the functions of a `.ThingClient` are intended to match those of the `.Thing` it's connected to, however there are currently some differences. In particular, `pydantic` models are usually converted to dictionaries. This is something that is on the long-term roadmap to improve, possibly with :ref:`code generation <client_codegen>`\ .
+
 .. [#events] Events are not yet implemented.
 
+.. _things_from_things:
+
+Using Things from other Things
+------------------------------
+
+Code within a Thing may access other Things on the same server using `.thing_slot`\ s. These are attributes of the `.Thing` that will be supplied by the server when it is set up. When you access a `.thing_slot` it will return the other `.Thing` instance, and it may be used like any other Python object. `.thing_slot`\ s may be optional, or may be configured to return multiple `.Thing` instances: see the `.thing_slot` documentation for more details.
+
 Using Things from other languages
 ----------------------------------
 
@@ -19,18 +30,7 @@ Dynamic class generation
 
 The object returned by `.ThingClient.from_url` is an instance of a dynamically-created subclass of `.ThingClient`. Dynamically creating the class is needed because we don't know what the methods and properties should be until we have downloaded the Thing Description. However, this means most code autocompletion tools, type checkers, and linters will not work well with these classes. In the future, LabThings-FastAPI will generate custom client subclasses that can be shared in client modules, which should fix these problems (see below).
 
-.. _things_from_things:
-
-Using Things from other Things
-------------------------------
-
-One goal of LabThings-FastAPI is to make code portable between a client (e.g. a Jupyter notebook, or a Python script on another computer) and server-side code (i.e. code inside an action of a `.Thing`). This is done using a `.DirectThingClient` class, which is a subclass of `.ThingClient`. 
-
-A `.DirectThingClient` class will call actions and properties of other `.Thing` subclasses using the same interface that would be used by a remote client, which means code for an action may be developed as an HTTP client, for example in a Jupyter notebook, and then moved to the server with minimal changes. Currently, there are a few differences in behaviour between working locally or remotely, most notably the return types (which are usually Pydantic models on the server, and currently dictionaries on the client). This should be improved in the future.
-
-It is also possible for a `.Thing` to access other `.Thing` instances directly. This gives access to functionality that is only available in Python, i.e. not available through a `.ThingClient` over HTTP. However, the `.Thing` must then be supplied manually with any :ref:`dependencies` required by its actions, and the public API as defined by the :ref:`wot_td` is no longer enforced.
-
-Actions that make use of other `.Thing` objects on the same server should access them using :ref:`dependencies`.
+.. _client_codegen:
 
 Planned future development: static code generation
 --------------------------------------------------

docs/source/wot_core_concepts.rst

@@ -61,4 +61,4 @@ Thing Description documents are higher-level than OpenAPI_ and focus on the capa
 Interaction Affordances
 -----------------------
 
-The Web of Things standard often talks about Affordances. This is the collective term for _wot_properties, _wot_actions, and _wot_events.
+The Web of Things standard often talks about Affordances. This is the collective term for :ref:`wot_properties`, :ref:`wot_actions`, and :ref:`wot_events`.

src/labthings_fastapi/actions/__init__.py

@@ -1,6 +1,6 @@
 """Actions module.
 
-:ref:`wot_actions` are represented by methods, decorated with the `.thing_action`
+:ref:`actions` are represented by methods, decorated with the `.thing_action`
 decorator.
 
 See the :ref:`actions` documentation for a top-level overview of actions in

src/labthings_fastapi/properties.py

@@ -1,6 +1,6 @@
 """Define properties of `.Thing` objects.
 
-:ref:`wot_properties` are attributes of a `.Thing` that may be read or written to
+:ref:`properties` are attributes of a `.Thing` that may be read or written to
 over HTTP, and they are described in :ref:`gen_docs`. They are implemented with
 a function `.property` (usually referenced as ``lt.property``), which is
 intentionally similar to Python's built in `property`.
@@ -216,7 +216,7 @@ def property(
 ) -> Value | FunctionalProperty[Value]:
     r"""Define a Property on a `.Thing`\ .
 
-    This function may be used to define :ref:`wot_properties` in
+    This function may be used to define :ref:`properties` in
     two ways, as either a decorator or a field specifier. See the
     examples in the :mod:`.property` documentation.
 

src/labthings_fastapi/utilities/introspection.py

@@ -64,7 +64,7 @@ def input_model_from_signature(
 
         LabThings-FastAPI does not currently support actions that take
         positional arguments, because this does not convert nicely into
-        JSONSchema or Thing Description documents (see :ref:`wot_td`).
+        JSONSchema or Thing Description documents (see :ref:`gen_docs`).
 
     :param func: the function to analyse.
     :param remove_first_positional_arg: Remove the first argument from the