Docs improvements (#112)

* Include jupyter notebooks in docs * Added FIJI plugin submodule * Added benchmarks and parameters section * added missing docs dependency * Remove old symlink creation * Reduce size of api_example.ipynb file * updates to `docs-improvement` PR (#57) * changed doc themes and updated faq * updated quickstart readme * added recursive checkout * updated docs * referred to fiji docs * updated formatting * WIP adding more content * updated quickstart references * updated installation * updated docs * removed extra space * added readme to docs * minor style and ordering changes * improved ultrack docs intro * add citation * added getting start docs * updated workflow to test docs * including pandoc install * fixing pandoc version * added configuration documentation & others * adding registration helper function * WIP optimizing docs section * ultrack tuning docs * removed docs testing branch setup * fixing faq links * fixing docs typo --------- Co-authored-by: Ilan <[email protected]>
royerlab · Jun 25, 2024 · 078d192 · 078d192
1 parent b6c113c
commit 078d192
Show file tree

Hide file tree

Showing 39 changed files with 1,036 additions and 151,349 deletions.
diff --git a/.github/workflows/docs.yml b/.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

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

diff --git a/.gitmodules b/.gitmodules
@@ -0,0 +1,3 @@
+[submodule "plugin-imagej"]
+	path = plugin-imagej
+	url = https://github.com/royerlab/ultrack-imagej
diff --git a/README.md b/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.
diff --git a/docs/README.md b/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
+```
diff --git a/docs/source/_static/css/style.css b/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;
+}
diff --git a/docs/source/api.rst b/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:

diff --git a/docs/source/cli.rst b/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
diff --git a/docs/source/conf.py b/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"
diff --git a/docs/source/configuration.rst b/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
diff --git a/docs/source/examples.rst b/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/**/*