Update tutorial and references

Author: emmuhamm

docs/how-to/use-handlers.md

@@ -8,7 +8,7 @@ Remember that by default, any messages received by the logger will be transmitte
 
 **In the future, this will be automatically generated from the docstrings.**
 
-For the full API reference (kwargs, types, defaults), see the [auto-generated reference](../reference/).
+For the full API reference (kwargs, types, defaults), see the [auto-generated reference](https://dune-daq.github.io/daqpytools/APIref).
 
 ---
 

docs/tutorial.md

@@ -1,14 +1,13 @@
 # Getting Started with Logging in DUNE-DAQ
 
-This is a very quick tutorial for someone entirely new to logging.
-
-**NEED TO WRITE THE TUTORIAL HEREE**. still a wip
-
-<!-- YOU SHOULD WRITE A BRIEF INTRO HERE: one paragraph orienting a brand new user to what they will accomplish by the end of this tutorial (e.g. "By the end of this page you will have a working logger printing coloured output to your terminal"). Keep it concrete and task-focused. -->
+By the end of this tutorial you will have a working logger printing colour-formatted output to your terminal. It should take about five minutes. No prior knowledge of Python logging is assumed — if you want to understand the concepts behind what you're doing, read [Concepts & explanation](./explanation.md) afterwards.
 
 ## Prerequisites
 
-<!-- YOU SHOULD WRITE ABOUT: what the reader needs before starting — DUNE environment loaded, daqpytools installed, etc. -->
+Before starting, make sure you have:
+
+- The DUNE DAQ environment loaded (i.e. `dbt-setup-env` or equivalent has been run in your shell)
+- `daqpytools` installed in your environment
 
 ## Step 1: Initialize a logger
 
@@ -29,6 +28,8 @@ test_logger = get_daq_logger(
 
 For now, **please see the docstring of `get_daq_logger` to see what stuff you can have and what to initialise with.**
 
+This gives you a named logger with a single Rich handler attached, emitting at `INFO` level and above. Loggers in daqpytools are singletons — calling `get_daq_logger` with the same name twice will return the same instance, so it's safe to call this once at module level and reuse it throughout your code.
+
 ## Step 2: Emit your first messages
 
 ```python
@@ -43,19 +44,20 @@ test_logger.info(
 )
 ```
 
-## Step 3: Explore with the logging demonstrator
+You should see colour-formatted output in your terminal, something like this:
 
-A lot of the available features can be demonstrated via the logging demonstrator functionality. With the DUNE environments loaded, simply run:
-
-```
-daqpytools-logging-demonstrator
-```
+![rich_demo](img/demo_rich.png)
 
-and view the help string to learn more, and view the script itself in the repository to see how it is implemented.
+The Rich handler supports the full [Rich markup syntax](https://rich.readthedocs.io/en/stable/markup.html) inline in your log messages.
 
 ## Next steps
 
+- To explore the full range of available handlers and filters interactively, run the logging demonstrator with the DUNE environments loaded:
+  ```
+  daqpytools-logging-demonstrator
+  ```
+  View the help string to learn more, and the script itself in the repository to see how it is implemented.
 - To understand *why* logging works the way it does, read the [Concepts & explanation](./explanation.md).
 - To learn how to use specific handlers and filters, see the [How-to guides](./how-to/).
-- For a full API reference, see the [Reference](./reference/).
+- For a full API reference, see the [API Ref](https://dune-daq.github.io/daqpytools/APIref).
 - If you are introducing logging to your Python repo, or upgrading an existing implementation, **please** read the [Logging best practices](./how-to/best-practices.md).

docs_dev/explanation.md

@@ -99,11 +99,11 @@ Defined in `specs.py`, there are two types:
 
 Specs are the "source of truth" for what a handler or filter is. When setup code needs to build something, it looks up the spec in a registry.
 
-![Specs](../img/Specs_class.png)
+![Specs](img/Specs_class.png)
 
 ### HandleIDFilter
 
-![Filtering](../img/Filter_class.png)
+![Filtering](img/Filter_class.png)
 
 `HandleIDFilter` is the core enforcement mechanism. Each handler gets one attached to it.
 
@@ -223,4 +223,4 @@ DUNEDAQ_ERS_WARNING="..."
 
 These are parsed into `ERSPyLogHandlerConf` objects that hold the handler list and optional protobuf endpoint for each severity.
 
-![LogHandlerConf](../img/LHC_class.png)
+![LogHandlerConf](img/LHC_class.png)