Add docs and deploy

.github/workflows/deploy-docs_ghpage.yml

@@ -0,0 +1,32 @@
+name: Deploy Docs to Pages
+
+permissions:
+  contents: write
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [ "emmuhamm/deploy-docs" ]   # or "develop"
+  # optional schedule:
+  # schedule:
+  #   - cron: "0 0 * * 6"
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r docs_dev/requirements.txt
+          # if you want mkdocstrings to import your package:
+          pip install .
+
+      - name: Deploy
+        run: mkdocs gh-deploy --force

.gitignore

@@ -28,6 +28,8 @@ share/python-wheels/
 MANIFEST
 .vscode
 
+docs/generated
+docs_dev/APIref
 # PyInstaller
 #  Usually these files are written by a python script from a template
 #  before PyInstaller builds the exe, so as to inject date/other infos into it.

docs/README.md → README.md

@@ -7,7 +7,7 @@ Set of importable tools used to simplify DAQ development in python.
 
 ## Scope
 This provides a set of tools that are used in python applications, along with their unit tests. Currently, the following tools are defined
- - logging - [code](https://github.com/DUNE-DAQ/daqpytools/tree/develop/src/daqpytools/logging), [wiki](https://github.com/DUNE-DAQ/daqpytools/wiki/Logging)
+ - logging - [code](https://github.com/DUNE-DAQ/daqpytools/tree/develop/src/daqpytools/logging)
 
 ## Indended use case
 This repo will serve as the indended source of distribution standard tooling. Any python tool that is used by multiple repositories should be defined here.
@@ -18,4 +18,7 @@ For general users, no setup is required - when developing your python applicatio
 from daqpytools.logging.logger import get_daq_logger
 log = get_daq_logger(...)
 ```
-For developers, see the developer wiki.
+
+For users, see [the user wiki](https://dune-daq-sw.readthedocs.io/en/latest/packages/daqpytools/)
+For developers, view [the developer wiki](https://dune-daq.github.io/daqpytools/)
+Note that the GitHub wiki is outdated and unmaintained. 

docs/diagrams/LogRecord_Activity.drawio

@@ -0,0 +1,157 @@
+<mxfile host="Electron" agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/29.6.1 Chrome/142.0.7444.265 Electron/39.8.0 Safari/537.36" version="29.6.1">
+  <diagram name="LogRecord Activity" id="log-record-activity">
+    <mxGraphModel dx="1019" dy="631" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="1050" pageHeight="1100" math="0" shadow="0">
+      <root>
+        <mxCell id="0" />
+        <mxCell id="1" parent="0" />
+        <mxCell id="2" parent="1" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;opacity=30;" value="" vertex="1">
+          <mxGeometry height="990" width="210" x="40" y="40" as="geometry" />
+        </mxCell>
+        <mxCell id="3" parent="1" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;opacity=30;" value="" vertex="1">
+          <mxGeometry height="990" width="230" x="250" y="40" as="geometry" />
+        </mxCell>
+        <mxCell id="4" parent="1" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#e1d5e7;strokeColor=#9673a6;opacity=30;" value="" vertex="1">
+          <mxGeometry height="990" width="290" x="480" y="40" as="geometry" />
+        </mxCell>
+        <mxCell id="5" parent="1" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;opacity=30;" value="" vertex="1">
+          <mxGeometry height="990" width="190" x="770" y="40" as="geometry" />
+        </mxCell>
+        <mxCell id="6" parent="1" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;" value="&lt;b&gt;Logger&lt;/b&gt;" vertex="1">
+          <mxGeometry height="30" width="210" x="40" y="40" as="geometry" />
+        </mxCell>
+        <mxCell id="7" parent="1" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fillColor=#fff2cc;strokeColor=#d6b656;fontSize=12;" value="&lt;b&gt;HandleIDFilter&lt;/b&gt;" vertex="1">
+          <mxGeometry height="30" width="230" x="250" y="40" as="geometry" />
+        </mxCell>
+        <mxCell id="8" parent="1" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fillColor=#e1d5e7;strokeColor=#9673a6;fontSize=12;" value="&lt;b&gt;Routing Strategy&lt;/b&gt;" vertex="1">
+          <mxGeometry height="30" width="290" x="480" y="40" as="geometry" />
+        </mxCell>
+        <mxCell id="9" parent="1" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fillColor=#d5e8d4;strokeColor=#82b366;fontSize=12;" value="&lt;b&gt;Handler&lt;/b&gt;" vertex="1">
+          <mxGeometry height="30" width="190" x="770" y="40" as="geometry" />
+        </mxCell>
+        <mxCell id="50" parent="1" style="text;html=1;align=center;verticalAlign=top;whiteSpace=wrap;rounded=0;fontSize=8;fontColor=#b09525;" value="&lt;i&gt;(per-handler routing filter)&lt;/i&gt;" vertex="1">
+          <mxGeometry height="15" width="230" x="250" y="68" as="geometry" />
+        </mxCell>
+        <mxCell id="51" parent="1" style="text;html=1;align=center;verticalAlign=top;whiteSpace=wrap;rounded=0;fontSize=8;fontColor=#9673a6;" value="&lt;i&gt;(AllowedHandlersStrategy)&lt;/i&gt;" vertex="1">
+          <mxGeometry height="15" width="290" x="480" y="68" as="geometry" />
+        </mxCell>
+        <mxCell id="10" parent="1" style="ellipse;whiteSpace=wrap;html=1;aspect=fixed;fillColor=#000000;strokeColor=#000000;" value="" vertex="1">
+          <mxGeometry height="30" width="30" x="130" y="95" as="geometry" />
+        </mxCell>
+        <mxCell id="11" parent="1" style="rounded=1;whiteSpace=wrap;html=1;arcSize=40;fillColor=#dae8fc;strokeColor=#6c8ebf;" value="Receive LogRecord&lt;br&gt;(with extra metadata)" vertex="1">
+          <mxGeometry height="50" width="170" x="60" y="145" as="geometry" />
+        </mxCell>
+        <mxCell id="12" parent="1" style="rounded=1;whiteSpace=wrap;html=1;arcSize=40;fillColor=#dae8fc;strokeColor=#6c8ebf;" value="Apply logger-level filters&lt;br&gt;(e.g. ThrottleFilter)" vertex="1">
+          <mxGeometry height="50" width="170" x="60" y="220" as="geometry" />
+        </mxCell>
+        <mxCell id="13" parent="1" style="rhombus;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;" value="Passes?" vertex="1">
+          <mxGeometry height="60" width="80" x="105" y="295" as="geometry" />
+        </mxCell>
+        <mxCell id="14" parent="1" style="rounded=1;whiteSpace=wrap;html=1;arcSize=40;fillColor=#f8cecc;strokeColor=#b85450;" value="Record&lt;br&gt;suppressed" vertex="1">
+          <mxGeometry height="40" width="110" x="270" y="303" as="geometry" />
+        </mxCell>
+        <mxCell id="15" parent="1" style="ellipse;html=1;shape=doubleCircle;whiteSpace=wrap;aspect=fixed;fillColor=#000000;strokeColor=#000000;" value="" vertex="1">
+          <mxGeometry height="20" width="20" x="315" y="360" as="geometry" />
+        </mxCell>
+        <mxCell id="16" parent="1" style="rounded=1;whiteSpace=wrap;html=1;arcSize=40;fillColor=#dae8fc;strokeColor=#6c8ebf;" value="Fan out record to&lt;br&gt;each attached handler" vertex="1">
+          <mxGeometry height="50" width="170" x="60" y="395" as="geometry" />
+        </mxCell>
+        <mxCell id="17" parent="1" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontSize=9;fontColor=#666666;" value="&lt;i&gt;For each attached handler&lt;/i&gt;" vertex="1">
+          <mxGeometry height="20" width="150" x="155" y="450" as="geometry" />
+        </mxCell>
+        <mxCell id="18" parent="1" style="rounded=1;whiteSpace=wrap;html=1;arcSize=40;fillColor=#fff2cc;strokeColor=#d6b656;" value="HandleIDFilter.filter()&lt;br&gt;invoked for this handler" vertex="1">
+          <mxGeometry height="50" width="190" x="275" y="480" as="geometry" />
+        </mxCell>
+        <mxCell id="19" parent="1" style="rounded=1;whiteSpace=wrap;html=1;arcSize=40;fillColor=#fff2cc;strokeColor=#d6b656;" value="Call get_allowed(record)&lt;br&gt;(delegates to strategy)" vertex="1">
+          <mxGeometry height="50" width="190" x="275" y="555" as="geometry" />
+        </mxCell>
+        <mxCell id="20" parent="1" style="rhombus;whiteSpace=wrap;html=1;fillColor=#e1d5e7;strokeColor=#9673a6;" value="Stream&lt;br&gt;type?" vertex="1">
+          <mxGeometry height="60" width="80" x="585" y="610" as="geometry" />
+        </mxCell>
+        <mxCell id="21" parent="1" style="rounded=1;whiteSpace=wrap;html=1;arcSize=40;fillColor=#e1d5e7;strokeColor=#9673a6;" value="&lt;font style=&quot;font-size: 10px;&quot;&gt;ERSAllowedHandlers:&lt;br&gt;resolve from OKS&lt;br&gt;based on log level&lt;/font&gt;" vertex="1">
+          <mxGeometry height="55" width="130" x="495" y="705" as="geometry" />
+        </mxCell>
+        <mxCell id="22" parent="1" style="rounded=1;whiteSpace=wrap;html=1;arcSize=40;fillColor=#e1d5e7;strokeColor=#9673a6;" value="&lt;font style=&quot;font-size: 8px;&quot;&gt;DefaultAllowedHandlers:&lt;br&gt;use record extras&lt;br&gt;or fallback_handlers (defined in HandleIDFilter)&lt;/font&gt;" vertex="1">
+          <mxGeometry height="55" width="130" x="635" y="705" as="geometry" />
+        </mxCell>
+        <mxCell id="23" parent="1" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#000000;strokeColor=#000000;" value="" vertex="1">
+          <mxGeometry height="5" width="190" x="530" y="785" as="geometry" />
+        </mxCell>
+        <mxCell id="24" parent="1" style="rounded=1;whiteSpace=wrap;html=1;arcSize=40;fillColor=#fff2cc;strokeColor=#d6b656;" value="Intersection check:&lt;br&gt;handler_ids ∩ allowed" vertex="1">
+          <mxGeometry height="45" width="190" x="275" y="805" as="geometry" />
+        </mxCell>
+        <mxCell id="25" parent="1" style="rhombus;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;" value="Non-&lt;br&gt;empty?" vertex="1">
+          <mxGeometry height="60" width="80" x="330" y="870" as="geometry" />
+        </mxCell>
+        <mxCell id="26" parent="1" style="rounded=1;whiteSpace=wrap;html=1;arcSize=40;fillColor=#f8cecc;strokeColor=#b85450;" value="Record dropped&lt;br&gt;for this handler" vertex="1">
+          <mxGeometry height="35" width="140" x="300" y="955" as="geometry" />
+        </mxCell>
+        <mxCell id="27" parent="1" style="ellipse;html=1;shape=doubleCircle;whiteSpace=wrap;aspect=fixed;fillColor=#000000;strokeColor=#000000;" value="" vertex="1">
+          <mxGeometry height="20" width="20" x="360" y="1000" as="geometry" />
+        </mxCell>
+        <mxCell id="28" parent="1" style="rounded=1;whiteSpace=wrap;html=1;arcSize=40;fillColor=#d5e8d4;strokeColor=#82b366;" value="Format and emit&lt;br&gt;record to destination" vertex="1">
+          <mxGeometry height="50" width="150" x="790" y="875" as="geometry" />
+        </mxCell>
+        <mxCell id="29" parent="1" style="ellipse;html=1;shape=doubleCircle;whiteSpace=wrap;aspect=fixed;fillColor=#000000;strokeColor=#000000;" value="" vertex="1">
+          <mxGeometry height="20" width="20" x="855" y="945" as="geometry" />
+        </mxCell>
+        <mxCell id="30" edge="1" parent="1" source="10" style="endArrow=classic;html=1;rounded=0;" target="11" value="">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="31" edge="1" parent="1" source="11" style="endArrow=classic;html=1;rounded=0;" target="12" value="">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="32" edge="1" parent="1" source="12" style="endArrow=classic;html=1;rounded=0;" target="13" value="">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="33" edge="1" parent="1" source="13" style="endArrow=classic;html=1;rounded=0;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;" target="14" value="No">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="34" edge="1" parent="1" source="14" style="endArrow=classic;html=1;rounded=0;" target="15" value="">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="35" edge="1" parent="1" source="13" style="endArrow=classic;html=1;rounded=0;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" target="16" value="Yes">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="36" edge="1" parent="1" source="16" style="endArrow=classic;html=1;rounded=0;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;" target="18" value="">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="37" edge="1" parent="1" source="18" style="endArrow=classic;html=1;rounded=0;" target="19" value="">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="38" edge="1" parent="1" source="19" style="endArrow=classic;html=1;rounded=0;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;" target="20" value="">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="39" edge="1" parent="1" source="20" style="endArrow=classic;html=1;rounded=0;" target="21" value="ERS">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="40" edge="1" parent="1" source="20" style="endArrow=classic;html=1;rounded=0;" target="22" value="Default">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="41" edge="1" parent="1" source="21" style="endArrow=classic;html=1;rounded=0;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.25;entryY=0;entryDx=0;entryDy=0;" target="23" value="">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="42" edge="1" parent="1" source="22" style="endArrow=classic;html=1;rounded=0;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.75;entryY=0;entryDx=0;entryDy=0;" target="23" value="">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="43" edge="1" parent="1" source="23" style="endArrow=classic;html=1;rounded=0;exitX=0;exitY=0.5;exitDx=0;exitDy=0;entryX=1;entryY=0.5;entryDx=0;entryDy=0;" target="24" value="Return allowed set">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="44" edge="1" parent="1" source="24" style="endArrow=classic;html=1;rounded=0;" target="25" value="">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="45" edge="1" parent="1" source="25" style="endArrow=classic;html=1;rounded=0;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" target="26" value="Empty">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="46" edge="1" parent="1" source="26" style="endArrow=classic;html=1;rounded=0;" target="27" value="">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="47" edge="1" parent="1" source="25" style="endArrow=classic;html=1;rounded=0;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;" target="28" value="Non-empty">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="48" edge="1" parent="1" source="28" style="endArrow=classic;html=1;rounded=0;" target="29" value="">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>