diff --git a/.readthedocs.yml b/.readthedocs.yml index 619e29d1..50688d3a 100644 --- a/.readthedocs.yml +++ b/.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 diff --git a/docs/requirements_doc.txt b/docs/requirements_doc.txt deleted file mode 100644 index 135cd2c2..00000000 --- a/docs/requirements_doc.txt +++ /dev/null @@ -1,16 +0,0 @@ -spikeextractors==0.9.0 -tqdm==4.48.2 -lazy_ops==0.2.0 -dill==0.3.2 -scipy==1.10.0 -PyYAML -h5py==2.9.0 -pynwb -nbsphinx -jupyter-sphinx -numpydoc -matplotlib -numpy -notebook -tifffile -git+https://github.com/catalystneuro/roiextractors diff --git a/docs/source/compatible.rst b/docs/source/compatible.rst index 80663ea3..225664fd 100644 --- a/docs/source/compatible.rst +++ b/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 `) +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 `_ (CNMF-E, EXTRACT) -#. `Caiman `_ -#. `SIMA `_ -#. `NWB `_ -#. `suite2p `_ -#. Numpy (for any currently un-supported format) - -Example Datasets ----------------- -Example datasets for each fo the file formats can be downloaded `here `_ + diff --git a/docs/source/conf.py b/docs/source/conf.py index 36119d95..a26ddd1e 100644 --- a/docs/source/conf.py +++ b/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", ""), +} diff --git a/docs/source/contribute.rst b/docs/source/contribute.rst index edcd1122..22adaa6d 100644 --- a/docs/source/contribute.rst +++ b/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 `_) +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 `_. +2. `pip install ` +3. `pip install roiextractors` + +More details on how to construct individual extractors can be found here: .. toctree:: :maxdepth: 1 diff --git a/docs/source/index.rst b/docs/source/index.rst index dc4bd2e0..82f72a0b 100644 --- a/docs/source/index.rst +++ b/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` diff --git a/requirements-rtd.txt b/requirements-rtd.txt new file mode 100644 index 00000000..9fdd2959 --- /dev/null +++ b/requirements-rtd.txt @@ -0,0 +1,8 @@ +Jinja2 +Sphinx +sphinx_rtd_theme +readthedocs-sphinx-search +sphinx-toggleprompt +sphinx-copybutton +roiextractors +pydata_sphinx_theme