Configuring the documentation for Sphinx and ReadTheDocs

.readthedocs.yaml

@@ -8,7 +8,7 @@ version: 2
 build:
   os: ubuntu-24.04
   tools:
-    python: "3.13"
+    python: "3.10"
 
 # Build documentation in the "docs/" directory with Sphinx
 sphinx:
@@ -17,7 +17,8 @@ sphinx:
 # Optionally, but recommended,
 # declare the Python requirements required to build your documentation
 # See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
-# python:
-#    install:
-#    - requirements: docs/requirements.txt
+python:
+   install:
+   - requirements: docs/requirements.txt
+   - requirements: requirements.txt
 

README.md

@@ -4,11 +4,7 @@
 
 **Linumpy** contains tools and utilities to quickly work with serial histology and microscopy data. Those tools implement the recommended workflows and parameters used in the lab. The library and scripts can be installed locally by using:
 
-```
-pip install linumpy
-```
-
-To install the tool for development, clone the repository and then install them with
+To install the tool, clone the repository and then install them with
 
 ```
 pip install -e .

docs/CONTRIBUTING.md

@@ -3,4 +3,6 @@
 * We use the [PEP8](https://peps.python.org/pep-0008/) coding standard
 * OME-Zarr format extension should be `ome.zarr`, as shown in the NGFF documentation ([URL](https://ngff.openmicroscopy.org/0.4/index.html#bf2raw-layout))
 * All scripts/methods should explicitly document the expected resolutions and dimensions units
+* We use Numpy style docstrings: https://numpydoc.readthedocs.io/en/latest/format.html
+* The axis order should be Z, Y, X
 

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,59 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath("../"))
+sys.path.insert(1, os.path.abspath("../scripts"))
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'linumpy'
+copyright = '2024, LINUM'
+author = 'LINUM'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'autoapi.extension',
+    "sphinx.ext.viewcode",
+    "sphinx.ext.napoleon",
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'autoapi.extension',
+    'sphinxarg.ext',
+]
+
+autoapi_dirs = ['../linumpy']
+autoapi_root = "api"
+autodoc_typehints = 'description'
+autoapi_ignore = ['*dev*']
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'furo'
+pygments_style = 'sphinx'
+
+# Napoleon settings
+napoleon_google_docstring = True
+napoleon_numpy_docstring = True
+napoleon_include_init_with_doc = False
+napoleon_include_private_with_doc = False
+napoleon_include_special_with_doc = True
+napoleon_use_admonition_for_examples = False
+napoleon_use_admonition_for_notes = False
+napoleon_use_admonition_for_references = False
+napoleon_use_ivar = False
+napoleon_use_param = True
+napoleon_use_rtype = True
+napoleon_preprocess_types = False
+napoleon_type_aliases = None
+napoleon_attr_annotations = True

docs/index.rst

@@ -0,0 +1,17 @@
+Welcome to the LINUMPY documentation!
+=====================================
+
+LINUMPY is a collection of tools to work with serial blockface histology data. These tools are developed by the `LINUM <https://linum-lab.ca>`_ lab at Université du Québec à Montréal (`UQAM <https://uqam.ca/>`_, Canada).
+
+.. toctree::
+   :maxdepth: 1
+
+   scripts
+   usage
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/requirements.txt

@@ -0,0 +1,4 @@
+sphinx
+sphinx-autoapi
+sphinx-argparse
+furo

docs/scripts.rst

@@ -0,0 +1,198 @@
+Scripts
+=======
+
+.. toctree::
+    :maxdepth: 1
+
+The following scripts are available in the `scripts` directory:
+
+linum_aip
+---------
+.. argparse::
+   :filename: ../scripts/linum_aip.py
+   :func: _build_arg_parser
+   :prog: linum_aip.py
+
+linum_compensate_attenuation
+----------------------------
+.. argparse::
+   :filename: ../scripts/linum_compensate_attenuation.py
+   :func: _build_arg_parser
+   :prog: linum_compensate_attenuation.py
+
+linum_compensate_for_psf
+------------------------
+.. argparse::
+   :filename: ../scripts/linum_compensate_for_psf.py
+   :func: _build_arg_parser
+   :prog: linum_compensate_for_psf.py
+
+linum_compensate_illumination_2d
+--------------------------------
+.. argparse::
+   :filename: ../scripts/linum_compensate_illumination_2d.py
+   :func: _build_arg_parser
+   :prog: linum_compensate_illumination_2d.py
+
+linum_compute_attenuation
+-------------------------
+.. argparse::
+   :filename: ../scripts/linum_compute_attenuation.py
+   :func: _build_arg_parser
+   :prog: linum_compute_attenuation.py
+
+linum_compute_attenuationBiasField
+----------------------------------
+.. argparse::
+   :filename: ../scripts/linum_compute_attenuationBiasField.py
+   :func: _build_arg_parser
+   :prog: linum_compute_attenuationBiasField.py
+
+linum_convert_bin_to_nii
+------------------------
+.. argparse::
+   :filename: ../scripts/linum_convert_bin_to_nii.py
+   :func: _build_arg_parser
+   :prog: linum_convert_bin_to_nii.py
+
+linum_convert_nifti_to_zarr
+---------------------------
+.. argparse::
+   :filename: ../scripts/linum_convert_nifti_to_zarr.py
+   :func: _build_arg_parser
+   :prog: linum_convert_nifti_to_zarr.py
+
+linum_convert_omezarr_to_nifti
+------------------------------
+.. argparse::
+   :filename: ../scripts/linum_convert_omezarr_to_nifti.py
+   :func: _build_arg_parser
+   :prog: linum_convert_omezarr_to_nifti.py
+
+linum_convert_zarr_to_omezarr
+-----------------------------
+.. argparse::
+   :filename: ../scripts/linum_convert_zarr_to_omezarr.py
+   :func: _build_arg_parser
+   :prog: linum_convert_zarr_to_omezarr.py
+
+linum_create_all_mosaicgrids_2d
+-------------------------------
+.. argparse::
+   :filename: ../scripts/linum_create_all_mosaicgrids_2d.py
+   :func: _build_arg_parser
+   :prog: linum_create_all_mosaicgrids_2d.py
+
+linum_create_mosaic_grid_2d
+---------------------------
+.. argparse::
+   :filename: ../scripts/linum_create_mosaic_grid_2d.py
+   :func: _build_arg_parser
+   :prog: linum_create_mosaic_grid_2d.py
+
+linum_create_mosaic_grid_3d
+---------------------------
+.. argparse::
+   :filename: ../scripts/linum_create_mosaic_grid_3d.py
+   :func: _build_arg_parser
+   :prog: linum_create_mosaic_grid_3d.py
+
+linum_crop_tiles_2d
+-------------------
+.. argparse::
+   :filename: ../scripts/linum_crop_tiles_2d.py
+   :func: _build_arg_parser
+   :prog: linum_crop_tiles_2d.py
+
+linum_detect_focal_curvature
+----------------------------
+.. argparse::
+   :filename: ../scripts/linum_detect_focal_curvature.py
+   :func: _build_arg_parser
+   :prog: linum_detect_focal_curvature.py
+
+linum_download_allen
+--------------------
+.. argparse::
+   :filename: ../scripts/linum_download_allen.py
+   :func: _build_arg_parser
+   :prog: linum_download_allen.py
+
+linum_estimate_illumination_2d
+------------------------------
+.. argparse::
+   :filename: ../scripts/linum_estimate_illumination_2d.py
+   :func: _build_arg_parser
+   :prog: linum_estimate_illumination_2d.py
+
+linum_estimate_transform_2d
+---------------------------
+.. argparse::
+   :filename: ../scripts/linum_estimate_transform_2d.py
+   :func: _build_arg_parser
+   :prog: linum_estimate_transform_2d.py
+
+linum_estimate_xyShift_fromMetadata
+-----------------------------------
+.. argparse::
+   :filename: ../scripts/linum_estimate_xyShift_fromMetadata.py
+   :func: _build_arg_parser
+   :prog: linum_estimate_xyShift_fromMetadata.py
+
+linum_fix_lateral_illumination_3d
+-----------------------------------
+.. argparse::
+   :filename: ../scripts/linum_fix_lateral_illumination_3d.py
+   :func: _build_arg_parser
+   :prog: linum_fix_lateral_illumination_3d.py
+
+linum_reorient_to_ras
+---------------------
+.. argparse::
+   :filename: ../scripts/linum_reorient_to_ras.py
+   :func: _build_arg_parser
+   :prog: linum_reorient_to_ras.py
+
+linum_resample_nifti
+--------------------
+.. argparse::
+   :filename: ../scripts/linum_resample_nifti.py
+   :func: _build_arg_parser
+   :prog: linum_resample_nifti.py
+
+linum_stack_slices
+------------------
+.. argparse::
+   :filename: ../scripts/linum_stack_slices.py
+   :func: _build_arg_parser
+   :prog: linum_stack_slices.py
+
+linum_stitch_2d
+---------------
+.. argparse::
+   :filename: ../scripts/linum_stitch_2d.py
+   :func: _build_arg_parser
+   :prog: linum_stitch_2d.py
+
+linum_stitch_3d
+---------------
+.. argparse::
+   :filename: ../scripts/linum_stitch_3d.py
+   :func: _build_arg_parser
+   :prog: linum_stitch_3d.py
+
+linum_view_omezarr
+------------------
+.. argparse::
+   :filename: ../scripts/linum_view_omezarr.py
+   :func: _build_arg_parser
+   :prog: linum_view_omezarr.py
+
+linum_view_zarr
+---------------
+.. argparse::
+   :filename: ../scripts/linum_view_zarr.py
+   :func: _build_arg_parser
+   :prog: linum_view_zarr.py
+
+

docs/usage.rst

@@ -0,0 +1,40 @@
+Usage
+=====
+
+The Nextflow workflows in the `workflow` directory can be used to perform reconstruction of the serial OCT data.
+
+Cluster Reconstruction
+----------------------
+To submit a reconstruction on a DigitalAlliance cluster (e.g. Béluga or Narval), you need to prepare a bash script describing the job parameters.
+Here's an example of such a script for a 2.5D reconstruction.
+
+.. note::
+
+    For this example, the nextflow pipeline file, nextflow configuration file and the Singularity image containing a compiled version of linumpy are in the same directory as the reconstruction directory. **See the workflow documentation to know how to adapt this example for your specific pipeline**
+
+.. code-block:: bash
+
+    #!/bin/sh
+    #SBATCH --nodes=1
+    #SBATCH --cpus-per-task=40
+    #SBATCH --mem=92G
+    #SBATCH --time=1:00:00
+    #SBATCH --mail-type=ALL
+    #SBATCH --mail-user=<YOUR_EMAIL_ADDRESS>
+    #SBATCH --account=<DIG_ALLIANCE_PROJECT_ID>
+
+    module load nextflow
+    module load apptainer
+
+    # Parameters
+    DIRECTORY=<FULL_PATH_TO_THE_RAW_DATA>
+    WORKFLOW_FILE=$DIRECTORY/workflow_reconstruction_2.5d.nf
+    CONFIG_FILE=$DIRECTORY/reconstruction_2.5d_beluga.config
+    SINGULARITY=$DIRECTORY/linumpy.sif
+
+    nextflow run $WORKFLOW_FILE -c $CONFIG_FILE -with-singularity $SINGULARITY \
+             --directory $DIRECTORY -resume
+
+
+
+