CONSTS description and image

Makefile

@@ -1,8 +1,9 @@
-.PHONY: test
+.PHONY: test doc docs
 
 # how to get into the python virtual environment
 source_venv := . .venv/bin/activate 
 
+doc docs: docs/
 docs/: .venv/ $(wildcard *.py) sphinx/conf.py $(wildcard sphinx/*.rst)
 	$(source_venv) && sphinx-build sphinx/ docs/
 

acq2sqlite.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 """
-convert db.txt into a sqlite database
+Convert ``db.txt`` into a sqlite database.
 """
 import sqlite3
 import logging
@@ -49,10 +49,24 @@ def column_names():
 
 class DBQuery:
     """
-    Convient SQL queries for tracking dicom headers/metadata
+    Convient SQL queries for tracking dicom headers/metadata.
     
-    Poorly implemented, ad-hoc bespoke ORM for ``schema.sql``
+    This class is a poorly implemented, ad-hoc/bespoke ORM for database defined in ``schema.sql``
     """
+
+    #: :py:data:`CONSTS` is a list of expected aquisition-invarient parameters.
+    #: The values of these attributes should be the same for every aquisition
+    #: sharing a ``Project × SequenceName`` pair (across all sessions of a Project).
+    #:
+    #: We consider the acquistion to have a Quallity Assurance error
+    #: when the value of any of these parameters in a single acquisition
+    #: fails to match the template.
+    #:
+    #: For example ``TR`` for task EPI acquistion identified by
+    #: ``SequenceName=RewardedAnti`` in ``Project=WPC-8620``
+    #: should always be ``1300`` ms.
+    #:
+    #: .. image:: ../../sphinx/imgs/nonconforming_example.png
     CONSTS = [
         "Project",
         "SequenceName",
@@ -121,14 +135,14 @@ def check_acq(self, d):
         cur = self.sql.execute(self.find_acq, acq_search_vals)
         acq = cur.fetchone()
         if acq:
-            logging.debug(f"have acq {acq[0]} {acq_search_vals}")
+            logging.info("have acq %s %s",acq[0], acq_search_vals)
             return True
         return False
 
     def param_rowid(self, d):
         """
         Find or insert the combination of parameters for an aquisition.
-        Using ``CONSTS``, the header parameters that should be invarient
+        Using :py:data:`CONSTS`, the header parameters that should be invarient
         across acquistions of the same name within a study.
 
         >>> db = DBQuery(sqlite3.connect(':memory:'))

change_header.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 """
-Modify DICOM header information.
+Modify DICOM header information to simulate failing QA.
 """
 import os
 from pathlib import Path

dcmmeta2tsv.py

@@ -81,7 +81,7 @@ def read_tags(dcm_path: os.PathLike, tags: TagDicts) -> list[str]:
     """
     :param dcm_path: dicom file with headers to extract
     :param tags: ordered dictionary with 'tag' key as hex pair, see :py:func:`tagpair_to_hex`
-    :return: list of tag values in same order as ``tags``
+    :return: list of tag values in same order as ``tags`` \
     BUT with CSA headers ``pedp``, ``ipat`` prepended
     """
     if not os.path.isfile(dcm_path):

sphinx/index.rst

@@ -8,6 +8,8 @@ mrrc-hdr-qa documentation
 
 Code to parse dicoms into a template database and alert on non-conforming sequences.
 
+Code
+--------
 
 .. toctree::
    :caption: Contents:
@@ -16,6 +18,29 @@ Code to parse dicoms into a template database and alert on non-conforming sequen
    :toctree: _autosummary
    :recursive:
 
-   change_header
    dcmmeta2tsv
    acq2sqlite
+   change_header
+
+
+Overview
+--------
+
+See :py:data:`acq2sqlite.DBQuery.CONSTS`
+
+.. image:: ../sphinx/imgs/nonconforming_example.png
+
+
+
+.. `https://dicom-parser.readthedocs.io/en/latest/siemens/csa_headers.html#csa-headers`_
+
+
+Parameters
+----------
+
+ .. csv-table:: Dicom tag list
+    :file: ../taglist.txt
+    :delimiter: \t
+    :header-rows: 1
+
+.. .. include:: ../readme.md