Update Docs

.readthedocs.yml

@@ -1,12 +1,13 @@
+version: "2"
+
 build:
-    image: latest
+  os: "ubuntu-22.04"
+  tools:
+    python: "3.10"
 
-version: 2
+python:
+  install:
+    - requirements: requirements-rtd.txt
 
 sphinx:
   configuration: docs/source/conf.py
-
-python:
-  version: 3.8
-  install:
-    - requirements: docs/requirements_doc.txt

docs/source/compatible.rst

@@ -1,25 +1,8 @@
 Supported formats
 =================
 
-Roiextractors supports various image formats obtained from different 2photon acquisition systems.
-It also supports well known post processing cell extraction/segmentation pipelines. If you use any other format and would like to see it being supported we would love to know! (:doc:`Contact <contact>`)
+The following is a live record of all the formats supported by ROIExtractors as well as other relevant ecosystem support.
 
-Imaging
--------
-1. HDF5
-2. TIFF
-3. STK
-4. FLI
+.. raw:: html
 
-Segmentation
-------------
-#. `calciumImagingAnalysis <https://github.com/bahanonu/calciumImagingAnalysis/>`_ (CNMF-E, EXTRACT)
-#. `Caiman <https://github.com/flatironinstitute/CaImAn/>`_
-#. `SIMA <http://www.losonczylab.org/sima/1.3.2//>`_
-#. `NWB <https://pynwb.readthedocs.io/en/stable//>`_
-#. `suite2p <https://github.com/MouseLand/suite2p/>`_
-#. Numpy (for any currently un-supported format)
-
-Example Datasets
-----------------
-Example datasets for each fo the file formats can be downloaded `here <https://gin.g-node.org/CatalystNeuro/ophys_testing_data/src/master/segmentation_datasets/>`_
+    <iframe style="width: 100%; height: 70vh; border: none;" src="https://catalystneuro.github.io/format-support-table/?tab=ophys-imaging"></iframe>

docs/source/conf.py

@@ -1,65 +1,72 @@
-# Configuration file for the Sphinx documentation builder.
-#
-# This file only contains a selection of the most common options. For a full
-# list see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
-
-# -- Path setup --------------------------------------------------------------
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-import os
 import sys
+from pathlib import Path
 
-sys.path.insert(0, os.path.abspath("."))
-
-
-# -- Project information -----------------------------------------------------
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
 
 project = "RoiExtractors"
 copyright = "2021, Saksham Sharda"
 author = "Saksham Sharda"
 
-# The full version, including alpha/beta/rc tags
-release = "0.2.1"
-
-
-# -- General configuration ---------------------------------------------------
-
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
-extensions = []
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ["_templates"]
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = []
-
-nbsphinx_execute_arguments = [
-    "--InlineBackend.figure_formats={'svg', 'pdf'}",
-    "--InlineBackend.rc={'figure.dpi': 96}",
+extensions = [
+    "sphinx.ext.napoleon",  # Support for NumPy and Google style docstrings
+    "sphinx.ext.autodoc",  # Includes documentation from docstrings in docs/api
+    "sphinx.ext.autosummary",  # Not clear. Please add if you know
+    "sphinx.ext.intersphinx",  # Allows links to other sphinx project documentation sites
+    "sphinx_search.extension",  # Allows for auto search function the documentation
+    "sphinx.ext.viewcode",  # Shows source code in the documentation
+    "sphinx.ext.extlinks",  # Allows to use shorter external links defined in the extlinks variable.
 ]
-# -- Options for HTML output -------------------------------------------------
-
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-#
-try:
-    import sphinx_rtd_theme
 
-    html_theme = "sphinx_rtd_theme"
-    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
-except ImportError:
-    print("RTD theme not installed, using default")
-    html_theme = "alabaster"
-
-# 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".
+templates_path = ["_templates"]
+master_doc = "index"
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+html_theme = "pydata_sphinx_theme"
 html_static_path = ["_static"]
+
+html_context = {
+    # "github_url": "https://github.com", # or your GitHub Enterprise site
+    "github_user": "catalystneuro",
+    "github_repo": "roiextractors",
+    "github_version": "main",
+    "doc_path": "docs",
+}
+
+linkcheck_anchors = False
+
+# --------------------------------------------------
+# Extension configuration
+# --------------------------------------------------
+
+# Napoleon
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+napoleon_use_param = False
+napoleon_use_ivar = True
+napoleon_include_init_with_doc = False
+napoleon_include_private_with_doc = True
+napoleon_include_special_with_doc = True
+
+# Autodoc
+autoclass_content = "both"  # Concatenates docstring of the class with that of its __init__
+autodoc_member_order = "bysource"  # Displays classes and methods by their order in source code
+autodata_content = "both"
+autodoc_default_options = {
+    "members": True,
+    "member-order": "bysource",
+    "private-members": True,
+    "show-inheritance": False,
+    "toctree": True,
+}
+add_module_names = False
+
+# Intersphinx
+intersphinx_mapping = {
+    "hdmf": ("https://hdmf.readthedocs.io/en/stable/", None),
+    "pynwb": ("https://pynwb.readthedocs.io/en/stable/", None),
+    "spikeinterface": ("https://spikeinterface.readthedocs.io/en/latest/", None),
+}
+
+# To shorten external links
+extlinks = {
+    "nwbinspector": ("https://nwbinspector.readthedocs.io/en/dev/%s", ""),
+}

docs/source/contribute.rst

@@ -1,7 +1,38 @@
 Contribute:
 ===========
 
-To contribute to Roiextractors to help us develop an api to handle a new data format for optophysiology:
+Example Datasets
+----------------
+
+Example datasets are maintained at https://gin.g-node.org/CatalystNeuro/ophys_testing_data.
+
+To download test data on your machine,
+
+1. Install the gin client (instructions `here <https://gin.g-node.org/G-Node/Info/wiki/GIN+CLI+Setup#linux>`_)
+2. Use gin to download data:
+
+   .. code-block:: bash
+
+      gin get CatalystNeuro/ophys_testing_data
+      cd ophys_testing_data
+      gin get-content
+
+3. Change the file at ``roiextractors/tests/gin_test_config.json`` to point to the path of this test data
+
+To update data later, ``cd`` into the test directory and run ``gin get-content``
+
+Troubleshooting
+---------------
+
+Installing SIMA with python>=3.7:
+________________________________
+Will need a manual installation for package dependency **SIMA** since it does not currently support python 3.7:
+
+1.   Download SIMA wheels distribution `here <https://www.lfd.uci.edu/~gohlke/pythonlibs/#sima>`_.
+2.  `pip install <download-path-to-wheels.whl>`
+3.  `pip install roiextractors`
+
+More details on how to construct individual extractors can be found here:
 
 .. toctree::
    :maxdepth: 1

docs/source/index.rst

@@ -10,7 +10,7 @@ Welcome to RoiExtractors's documentation!
 Roiextractors is a library that helps in analyzing, visualizing and interacting with optical physiology data acquired from various acquisition systems.
 
 **ROI**
-   Stands for Region Of Interest, which is the region in a set of acquired fluorescence images which the segmentation software has determined as a neuron.
+   Stands for Region Of Interest, which is the set of pixels from acquired fluorescence images which the segmentation software has determined to follow a particular cellular structure.
 
 With this package, a user can:
 
@@ -20,9 +20,7 @@ With this package, a user can:
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
-   :glob:
-   :numbered:
+   :caption: Contents
 
    gettingstarted
    compatible
@@ -31,10 +29,3 @@ With this package, a user can:
    contribute
    licence
    contact
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`

requirements-rtd.txt

@@ -0,0 +1,8 @@
+Jinja2
+Sphinx
+sphinx_rtd_theme
+readthedocs-sphinx-search
+sphinx-toggleprompt
+sphinx-copybutton
+roiextractors
+pydata_sphinx_theme