Working on docs

votchallenge · Mar 14, 2024 · 85d88e3 · 85d88e3
1 parent af15c1f
commit 85d88e3
Show file tree

Hide file tree

Showing 11 changed files with 57 additions and 26 deletions.
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -0,0 +1,23 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# We recommend specifying your dependencies to enable reproducible builds:
+# https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+   - requirements: docs/requirements.txt
+   - requirements: requirements.txt
diff --git a/docs/api.rst b/docs/api.rst
@@ -8,15 +8,15 @@ The API section contains the generated documentation of individual structures an
 
    api/analysis
    api/dataset
-   api/document
+   api/report
    api/experiment
    api/region
    api/stack
    api/tracker
    api/utilities
 
-Core utilities
---------------
+Configuration
+-------------
 
 .. automodule:: vot
    :members:
diff --git a/docs/api/analysis.rst b/docs/api/analysis.rst
@@ -7,7 +7,7 @@ enables efficient execution of large-scale evaluations.
 .. automodule:: vot.analysis
    :members:
 
-.. automodule:: vot.analysis.parallel
+.. automodule:: vot.analysis.processor
    :members:
 
 Accuracy analysis
@@ -19,7 +19,7 @@ Accuracy analysis
 Failure analysis
 ----------------
 
-.. automodule:: vot.analysis.failure
+.. automodule:: vot.analysis.failures
    :members:
 
 Long-term measures
@@ -37,5 +37,5 @@ Multi-start measures
 Supervision analysis
 --------------------
 
-.. automodule:: vot.analysis.supervision
+.. automodule:: vot.analysis.supervised
    :members:
diff --git a/docs/api/dataset.rst b/docs/api/dataset.rst
@@ -4,7 +4,7 @@ Dataset module
 .. automodule:: vot.dataset
    :members:
 
-.. automodule:: vot.datase.common
+.. automodule:: vot.dataset.common
    :members:
 
 Extended dataset support

diff --git a/docs/api/document.rst → docs/api/report.rst b/docs/api/document.rst → docs/api/report.rst
@@ -1,5 +1,5 @@
 Report module
-============
+=============
 
 .. automodule:: vot.report
    :members:
@@ -8,13 +8,13 @@ Report module
    :members:
 
 HTML report generation
-------------------------
+----------------------
 
 .. automodule:: vot.report
    :members:
 
 LaTeX report generation
--------------------------
+-----------------------
 
 .. automodule:: vot.report.latex
    :members:

diff --git a/docs/conf.py b/docs/conf.py
@@ -2,10 +2,11 @@
 #
 import os
 import sys
-sys.path.insert(0, os.path.abspath('../python'))
+sys.path.insert(0, os.path.abspath('..'))
 
 # -- General configuration ------------------------------------------------
 
+print(sys.path)
 
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']
 
@@ -24,7 +25,7 @@
 
 # General information about the project.
 project = u'VOT Toolkit'
-copyright = u'2022, Luka Cehovin Zajc'
+copyright = u'2024, Luka Cehovin Zajc'
 author = u'Luka Cehovin Zajc'
 
 try:
@@ -47,7 +48,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:

diff --git a/docs/index.rst b/docs/index.rst
@@ -1,14 +1,14 @@
 Welcome to the VOT Toolkit documentation
 ========================================
 
-The VOT toolkit is the official evaluation tool for the [Visual Object Tracking (VOT) challenge](http://votchallenge.net/). 
+The VOT toolkit is the official evaluation tool for the `Visual Object Tracking (VOT) challenge <https://votchallenge.net/>`_. 
 It is written in Python 3 language. The toolkit is designed to be easy to use and to have broad support for various trackers,
 datasets and evaluation measures.
 
 Contributions and development
 -----------------------------
 
-The VOT toolkit is developed by the VOT Committee, primarily by Luka Čehovin Zajc and the tracking community as an open-source project (GPLv3 license). 
+The VOT toolkit is developed by the VOT Committee, primarily by `Luka Čehovin Zajc <https://vicos.si/people/luka_cehovin_zajc/>`_ and the tracking community as an open-source project (GPLv3 license). 
 
 Contributions to the VOT toolkit are welcome, the preferred way to do it is by submitting an issue or a pull requests on `GitHub <https://github.com/votchallenge/toolkit>`_.
 

diff --git a/docs/overview.rst b/docs/overview.rst
@@ -1,7 +1,7 @@
 Overview
 ========
 
-The toolkit is designed as a modular framework with several modules that address different aspects of the performance evaluation problem.
+The toolkit is organized as a modular collection of classes and methods with several modules that address different aspects of the performance evaluation problem.
 
 Key concepts
 ------------
@@ -15,27 +15,27 @@ Key concepts that are used throughout the toolkit are:
 * **Analysis** - an analysis is a set of **measures** that are used to evaluate the performance of a tracker (compare predicted trajectories to groundtruth).
 * **Stack** - a stack is a collection of **experiments** and **analyses** that are performed on a given dataset.
 * **Workspace** - a workspace is a collection of experiments and analyses that are performed on a given dataset.
+* **Report** - a report is a representation of a list of analyses for a given experiment stack.
 
 Tracker support
 ---------------
 
 The toolkit supports various ways of interacting with a tracking methods. Primary manner (at the only supported at the moment) is using the TraX protocol. 
-The toolkit provides a wrapper for the TraX protocol that allows to use any tracker that supports the protocol.
+The toolkit provides a wrapper for the TraX protocol that allows to use any tracker that supports the protocol. Other ways of interacting with a tracker can be added in the future.
 
 Dataset support
 ---------------
 
-The toolkit is capable of using any dataset that is provided in the toolkit format. 
+The toolkit is capable of using any dataset that is provided in the official format or by registering a custom loaders.
 The toolkit format is a simple directory structure that contains a set of sequences. Each sequence is a directory that contains a set of frames and a groundtruth file. 
 The groundtruth file is a text file that contains one line per frame. Each line contains the bounding box of the object in the frame in the format `x,y,w,h`. The toolkit format is used by the toolkit itself and by the VOT challenges.
 
-
 Performance methodology support
 -------------------------------
 
 Various performance measures and visualzatons are implemented, most of them were used in VOT challenges.
 
  * **Accuracy** - the accuracy measure is the overlap between the predicted and groundtruth bounding boxes. The overlap is measured using the intersection over union (IoU) measure.
- * **Robustness** - the robustness measure is the number of failures of the tracker. A failure is defined as the overlap between the predicted and groundtruth bounding boxes being less than 0.5.
+ * **Robustness** - the robustness measure is the number of failures of the tracker. A failure is defined as the overlap between the predicted and groundtruth bounding boxes being less than a certain threshold.
  * **Expected Average Overlap** - the expected average overlap (EAO) is a measure that combines accuracy and robustness into a single measure. The EAO is computed as the area under the accuracy-robustness curve.
  * **Expected Overlap** - the expected overlap (EO) is a measure that combines accuracy and robustness into a single measure. The EO is computed as the area under the accuracy-robustness curve.
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1,4 @@
+sphinx==5.3.0
+sphinx_rtd_theme==1.1.1
+readthedocs-sphinx-search==0.1.1
+recommonmark=0.7.1
diff --git a/vot/report/__init__.py b/vot/report/__init__.py
@@ -210,6 +210,7 @@ def __init__(self, identifier: str, frames: FrameList, trait=None):
         self._regions = {}
 
     def draw(self, frame, key, data):
+        """Draws the data on the frame."""
         from vot.region import Region
         assert isinstance(data, Region)
 
@@ -219,6 +220,7 @@ def draw(self, frame, key, data):
         self._regions[key][frame] = data
 
     def render(self, frame: int):
+        """Renders the frame and returns it as an array."""
         from vot.utilities.draw import ImageDrawHandle
 
         assert frame >= 0 and frame < len(self)
@@ -471,7 +473,7 @@ def make_figure(self, trait=None) -> typing.Tuple[Figure, Axes]:
         """ Makes the figure for the given trait.
         
         Args:
-            trait: The trait for which to make the figure.
+            trait (str): The trait for which to make the figure.
 
         Returns:
             A tuple containing the figure and the axes.
@@ -519,13 +521,13 @@ class TrackerSorter(Attributee):
     analysis = String(default=None)
     result = Integer(val_min=0, default=0)
 
-    def __call__(self, experiments, trackers, sequences):
+    def __call__(self, experiments: typing.List["Experiment"], trackers: typing.List["Tracker"], sequences: typing.List["Sequence"]):
         """ Sorts the trackers. 
         
         Arguments:
-            experiments (list of Experiment): The experiments.
-            trackers (list of Tracker): The trackers.
-            sequences (list of Sequence): The sequences.
+            experiments (typing.List[Experiment]): The experiments.
+            trackers (typing.List[Tracker]): The trackers.
+            sequences (typing.List[Sequence]): The sequences.
             
         Returns:
             A list of indices of the trackers in the sorted order.
@@ -667,7 +669,7 @@ def generate_document(workspace: "Workspace", trackers: typing.List[Tracker], fo
     """Generate a report for a one or multiple trackers on an experiment stack and a set of sequences.
 
     Args:
-        workspace: The workspace to use for the report.
+        workspace (Workspace): The workspace to use for the report.
         trackers: The trackers to include in the report.
         format: The format of the report.
         name: The name of the report.

diff --git a/vot/report/html.py b/vot/report/html.py
@@ -122,6 +122,7 @@ def add_script(name, linked=False):
 
     # TODO: make table more general (now it assumes a tracker per row)
     def make_table(data: Table):
+        """Generates a table from a Table object."""
         if len(data.header[2]) == 0:
             logger.debug("No measures found, skipping table")
         else: