Docs improvements

.github/workflows/docs.yml

@@ -24,6 +24,13 @@ jobs:
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
+          submodules: 'true'
+
+      - name: Pandoc install
+        uses: pandoc/actions/[email protected]
+        with:
+          version: 2.19
+
       - name: Setup Pages
         id: pages
         uses: actions/configure-pages@v5

.gitignore

@@ -169,6 +169,7 @@ cython_debug/
 examples/*/*
 !examples/*/*.ipynb
 !examples/*/*.yml
+docs/source/examples
 
 # ultrack files
 metadata.toml

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "plugin-imagej"]
+	path = plugin-imagej
+	url = https://github.com/royerlab/ultrack-imagej

README.md

@@ -51,7 +51,7 @@ The official documentation is available [here](https://royerlab.github.io/ultrac
 
 These additional developer documentation are available:
 
-- Parameter [configuration schema](ultrack/config/README.md).
+- Parameter [configuration schema](docs/source/configuration.rst).
 - Intermediate segmentation and tracking SQL database are [here](ultrack/core/README.md).
 
 ## Gurobi setup
@@ -92,8 +92,10 @@ Depending on the operating system, the gurobi library might be missing and you n
 
 ## Citing
 
+If you use ultrack in your research, please cite the following paper:
+
 ```
-@misc{bragantini2023ultrack,
+@misc{bragantini2023ucmtracking,
       title={Large-Scale Multi-Hypotheses Cell Tracking Using Ultrametric Contours Maps},
       author={Jordão Bragantini and Merlin Lange and Loïc Royer},
       year={2023},
@@ -102,3 +104,5 @@ Depending on the operating system, the gurobi library might be missing and you n
       primaryClass={cs.CV}
 }
 ```
+
+And the respective auxiliary methods (e.g. Cellpose, napari, etc) depending on your usage.

docs/README.md

@@ -0,0 +1,29 @@
+# Building docs instructions
+
+This assumes you have already cloned the repository and are in the root directory of the repository.
+
+Go to the docs directory and install the requirements
+
+```bash
+cd docs
+pip install '..[docs]'
+```
+
+Clean and build the docs with
+
+```bash
+make clean
+make html
+```
+
+In Linux, open the generated html file with
+
+```bash
+xdg-open build/html/index.html
+```
+
+or in macOS
+
+```bash
+open build/html/index.html
+```

docs/source/_static/css/style.css

@@ -0,0 +1,27 @@
+p {
+    line-height: 1.5;  /* Adjust this value as needed */
+    margin-top: 5px;    /* Space above each paragraph */
+    margin-bottom: 0px; /* Space below each paragraph */
+}
+
+li {
+    margin-top: 0px;    /* Adjust this value as needed */
+    margin-bottom: 0px; /* Adjust this value as needed */
+}
+
+ul, ol {
+    margin-top: 0px;  /* Margin around the list */
+}
+
+h1 {
+    margin-top: 40px;
+}
+
+h2 {
+    margin-top: 30px;
+}
+
+h3 {
+    margin-top: 20px;
+    font-size: 1.0em;
+}

docs/source/api.rst

@@ -1,13 +1,18 @@
 API
----
+===
+
+First, we provide a summary of the main functionalities of the package.
+Then we provide detailed documentation of every public function of ultrack.
 
 Object Oriented API
+^^^^^^^^^^^^^^^^^^^
 
 .. autosummary::
 
     ultrack.Tracker
 
 Core functionalities
+^^^^^^^^^^^^^^^^^^^^
 
 .. autosummary::
 
@@ -21,15 +26,23 @@ Core functionalities
 .. could not make it work for ultrack.utils.array
 
 Image processing utilities
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. autosummary::
 
-    ultrack.imgproc.segmentation.Cellpose
-    ultrack.imgproc.plantseg.PlantSeg
-    ultrack.imgproc.sam
-    ultrack.imgproc.flow
+    ultrack.imgproc.PlantSeg
+    ultrack.imgproc.detect_foreground
+    ultrack.imgproc.inverted_edt
+    ultrack.imgproc.normalize
+    ultrack.imgproc.robust_invert
+    ultrack.imgproc.tracks_properties
+    ultrack.imgproc.Cellpose
+    ultrack.imgproc.sam.MicroSAM
+    ultrack.imgproc.register_timelapse
+    ultrack.imgproc.flow.timelapse_flow
 
 Exporting
+^^^^^^^^^
 
 .. autosummary::
 
@@ -57,15 +70,9 @@ Array utilities
 Image processing utilities
 ==========================
 
--------------------
-DL models interface
--------------------
-
-.. autoclass:: ultrack.imgproc.segmentation.Cellpose
-    :members:
-
-.. autoclass:: ultrack.imgproc.plantseg.PlantSeg
+.. automodule:: ultrack.imgproc
     :members:
+    :imported-members:
 
 .. automodule:: ultrack.imgproc.sam
     :members:

docs/source/cli.rst

@@ -1,25 +1,39 @@
 CLI
 ---
 
+.. click:: ultrack.cli.flow:add_flow_cli
+    :prog: ultrack flow
+
+.. click:: ultrack.cli.check_gurobi:check_gurobi_cli
+    :prog: ultrack check_gurobi
+
+.. click:: ultrack.cli.clear_database:clear_database_cli
+    :prog: ultrack clear_database
 
 .. click:: ultrack.cli.config:config_cli
     :prog: ultrack create_config
 
-.. click:: ultrack.cli.segment:segmentation_cli
-    :prog: ultrack segment
+.. click:: ultrack.cli.data_summary:data_summary_cli
+    :prog: ultrack data_summary
 
-.. click:: ultrack.cli.flow:add_flow_cli
-    :prog: ultrack flow
+.. click:: ultrack.cli.estimate_params:estimate_params_cli
+    :prog: ultrack estimate_params
+
+.. click:: ultrack.cli.export:export_cli
+    :prog: ultrack export
+    :nested: full
+
+.. click:: ultrack.cli.labels_to_edges:labels_to_contours_cli
+    :prog: ultrack labels_to_contours
 
 .. click:: ultrack.cli.link:link_cli
     :prog: ultrack link
 
+.. click:: ultrack.cli.segment:segmentation_cli
+    :prog: ultrack segment
+
 .. click:: ultrack.cli.solve:solve_cli
     :prog: ultrack solve
 
-.. click:: ultrack.cli.export:export_cli
-    :prog: ultrack export
-    :nested: full
-
-.. click:: ultrack.cli.clear_database:clear_database_cli
-    :prog: ultrack clear_database
+.. click:: ultrack.cli.server:server_cli
+    :prog: ultrack server

docs/source/conf.py

@@ -16,11 +16,20 @@
 
 sys.path.insert(0, os.path.abspath("../.."))
 
+if not os.path.exists("examples"):
+    os.symlink("../../examples", "examples", target_is_directory=True)
+
 # -- Project information -----------------------------------------------------
 
 project = "ultrack"
-copyright = "2023, Jordão Bragantini"
-author = "Jordão Bragantini"
+copyright = "2024, Jordão Bragantini"
+author = "Jordão Bragantini, Ilan Theodoro & contributors"
+
+# The title of the HTML documentation (appears in the sidebar)
+html_title = "ultrack"
+
+# The short title for the HTML documentation (appears in the navigation bar)
+html_short_title = "ultrack"
 
 # The full version, including alpha/beta/rc tags
 release = libversion("ultrack")
@@ -30,7 +39,22 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ["sphinx.ext.autodoc", "sphinx_click.ext", "sphinx.ext.autosummary"]
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx_click.ext",
+    "sphinx_copybutton",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.mathjax",
+    "nbsphinx",
+    "myst_parser",
+    "sphinx_gallery.load_style",
+    "sphinxcontrib.autodoc_pydantic",
+]
+
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -45,18 +69,34 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "sphinx_rtd_theme"
+html_theme = "furo"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
 
+html_css_files = [
+    "css/style.css",
+]
+
 # -- AutoDoc configuration --------------------------------------------------
 
 # Automatically extract typehints when specified and place them in
 # descriptions of the relevant function/method.
-autodoc_typehints = "description"
+autodoc_typehints = "none"
 
 # Don't show class signature with the class' name.
 # autodoc_class_signature = "separated"
+
+# Pydantic auto-doc settings
+autodoc_pydantic_model_show_json = False
+autodoc_pydantic_model_show_config_summary = False
+autodoc_pydantic_model_show_validator_summary = False
+autodoc_pydantic_model_show_validator_members = False
+autodoc_pydantic_model_show_field_summary = False
+autodoc_pydantic_model_signature_prefix = "class"
+autodoc_pydantic_field_list_validators = False
+autodoc_pydantic_model_undoc_members = False
+autodoc_pydantic_model_summary_list_order = "bysource"
+autodoc_pydantic_model_member_order = "bysource"

docs/source/configuration.rst

@@ -0,0 +1,35 @@
+Configuration
+-------------
+
+The configuration is at the heart of ultrack, it is used to define the parameters for each step of the pipeline and where to store the intermediate results.
+The `MainConfig` is the main configuration that contains the other configurations of the individual steps plus the data configuration.
+
+The configurations are documented below, the parameters are ordered by importance, most important parameters are at the top of the list. Parameters that should not be changed in most of the cases are at the bottom of the list and contain a ``SPECIAL`` tag.
+
+.. autosummary::
+
+    ultrack.config.MainConfig
+    ultrack.config.DataConfig
+    ultrack.config.SegmentationConfig
+    ultrack.config.LinkingConfig
+    ultrack.config.TrackingConfig
+
+---------------
+
+.. autopydantic_model:: ultrack.config.MainConfig
+
+---------------
+
+.. autopydantic_model:: ultrack.config.DataConfig
+
+---------------
+
+.. autopydantic_model:: ultrack.config.SegmentationConfig
+
+---------------
+
+.. autopydantic_model:: ultrack.config.LinkingConfig
+
+---------------
+
+.. autopydantic_model:: ultrack.config.TrackingConfig

docs/source/examples.rst

@@ -0,0 +1,15 @@
+Examples
+--------
+
+.. include:: examples/README.rst
+   :start-line: 2
+   :end-line: 25
+
+Notebooks
+---------
+
+.. nbgallery::
+    :maxdepth: 2
+    :glob:
+
+    examples/**/*