docs: fix docs build, fix all build warnings, enable strict mode

.readthedocs.yml

@@ -14,6 +14,7 @@ build:
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
    configuration: docs/source/conf.py
+   fail_on_warning: true
 
 python:
   install:

README.md

@@ -35,7 +35,7 @@ Matchers take a ground truth and a predicted TrackingGraph with optional segment
 Metrics are then computed on the matched graphs, and a summary is printed out.
 
 The `traccuracy` library has a command line interface for running common metrics
-pipelines, documented [here](https://traccuracy.readthedocs.io/en/latest/cli.html), and a flexible Python API, shown in [this](https://traccuracy.readthedocs.io/en/latest/examples/ctc.html) example notebook.
+pipelines, [documented here](https://traccuracy.readthedocs.io/en/latest/cli.html), and a flexible Python API, shown in [this](https://traccuracy.readthedocs.io/en/latest/examples/ctc.html) example notebook.
 
 
 ## Implemented Metrics

docs/source/cli.rst

@@ -4,4 +4,3 @@ CLI
 .. click:: traccuracy.cli:typer_click_object
    :prog: traccuracy
    :nested: full
-

docs/source/conf.py

@@ -48,7 +48,7 @@
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
     "IPython.sphinxext.ipython_console_highlighting",  # code highlighting in notebooks
-    "m2r2",  # include md files in rst files
+    "myst_parser",  # include md files in rst files
     "autoapi.extension",  # autobuild api docs
     "nbsphinx",  # add notebooks to docs
     "nbsphinx_link",  # add notebooks to docs

docs/source/index.rst

@@ -1,4 +1,5 @@
-.. mdinclude:: ../../README.md
+.. include:: ../../README.md
+   :parser: myst_parser.sphinx_
 
 .. toctree::
    :maxdepth: 2
@@ -12,5 +13,5 @@
    :hidden:
    :caption: Traccuracy API:
 
-   autoapi/traccuracy/index
-   cli
+   autoapi/index
+   cli

pyproject.toml

@@ -57,18 +57,14 @@ dev = [
     "ruff",
 ]
 docs = [
-    "mock",
-    "Sphinx<6",
-    "sphinx-rtd-theme>=0.5.2 ",
-    "m2r2<0.3.3",
-    "sphinx-autoapi",
-    "nbsphinx",
-    "nbsphinx-link",
-    "sphinx-click",
-    "ipython",
-    "docutils~=0.16.0"
-    # had to pin versions because of sphinx list rendering bug
-    # https://stackoverflow.com/questions/67542699/readthedocs-sphinx-not-rendering-bullet-list-from-rst-file
+    "ipython==8.17.1",
+    "myst-parser==2.0.0",
+    "nbsphinx-link==1.3.0",
+    "nbsphinx==0.9.3",
+    "sphinx-autoapi==3.0.0",
+    "sphinx-click==5.0.1",
+    "sphinx-rtd-theme==1.3.0",
+    "Sphinx==7.2.6",
 ]
 
 [project.urls]

src/traccuracy/_tracking_graph.py

@@ -90,7 +90,7 @@ class TrackingGraph:
     time frame and location of each node is not mutated after construction,
     although non-spatiotemporal attributes of nodes and edges can be modified freely.
 
-    Attributes
+    Attributes:
         start_frame: int, the first frame with a node in the graph
         end_frame: int, the end of the span of frames containing nodes
             (one frame after the last frame that contains a node)
@@ -304,7 +304,7 @@ def get_nodes_by_roi(self, **kwargs):
         signify an unbounded ROI on that side.
 
         For example, if frame_key='t' and location_keys=('x', 'y'):
-            `graph.get_nodes_by_roi(t=(10, None), x=(0, 100))`
+        `graph.get_nodes_by_roi(t=(10, None), x=(0, 100))`
         would return all nodes with time >= 10, and 0 <= x < 100, with no limit
         on the y values.
 

src/traccuracy/cli.py

@@ -41,7 +41,7 @@ def run_ctc(
     """
     Run TRA and DET metric on gt and pred data using CTC matching.
 
-    If --gt_track_path and --pred_track_path are not passed, we find *_track.txt
+    If --gt_track_path and --pred_track_path are not passed, we find ``*_track.txt``
     files in the data directories. If more than one such file is present, or
     no such files are present, an error is raised.
 
@@ -99,7 +99,7 @@ def run_aogm(
 ):
     """Run general AOGM measure on gt and pred data using CTC matching.
 
-    If gt_track_path and pred_track_path are not passed, we find *_track.txt
+    If gt_track_path and pred_track_path are not passed, we find ``*_track.txt``
     files in the data directories. If more than one such file is present, or
     no such files are present, an error is raised.
 
@@ -163,7 +163,7 @@ def run_divisions_on_iou(
 ):
     """Run division metrics on gt and pred data using IOU matching.
 
-    If --gt_track_path and --pred_track_path are not passed, we find *_track.txt
+    If --gt_track_path and --pred_track_path are not passed, we find ``*_track.txt``
     files in the data directories. If more than one such file is present, or
     no such files are present, an error is raised.
 
@@ -222,7 +222,7 @@ def run_divisions_on_ctc(
 ):
     """Run division metrics on gt and pred data using CTC matching.
 
-    If --gt_track_path and --pred_track_path are not passed, we find *_track.txt
+    If --gt_track_path and --pred_track_path are not passed, we find ``*_track.txt``
     files in the data directories. If more than one such file is present, or
     no such files are present, an error is raised.
 

src/traccuracy/loaders/_ctc.py

@@ -163,7 +163,7 @@ def load_ctc_data(data_dir, track_path=None):
     Args:
         data_dir (str): Path to directory containing CTC tiffs.
         track_path (optional, str): Path to CTC track file. If not passed,
-        finds '*_track.txt' in data_dir.
+            finds `*_track.txt` in data_dir.
 
     Returns:
         TrackingData: Object containing segmentations and TrackingGraph.

src/traccuracy/matchers/_iou.py

@@ -52,8 +52,8 @@ def match_iou(gt, pred, threshold=0.6):
     and that the label is recorded on each node using label_key
 
     Args:
-        gt (TrackingGraph): Tracking data object containing graph and segmentations
-        pred (TrackingGraph): Tracking data object containing graph and segmentations
+        gt (traccuracy.TrackingGraph): Tracking data object containing graph and segmentations
+        pred (traccuracy.TrackingGraph): Tracking data object containing graph and segmentations
         threshold (float, optional): Minimum IoU for matching cells. Defaults to 0.6.
 
     Returns:

src/traccuracy/metrics/_divisions.py

@@ -13,6 +13,7 @@
 which the exact frame that a division event occurs is somewhat arbitrary due to
 a high frame rate or variable segmentation or detection. Consider the following
 graphs as an example::
+
     G1
                                 2_4
     1_0 -- 1_1 -- 1_2 -- 1_3 -<