Merge pull request #3188 from chrishalcrow/eradicate-sphinx-warnings

Eradicate sphinx warnings

Author: samuelgarcia

doc/api.rst

@@ -338,59 +338,58 @@ spikeinterface.curation
 spikeinterface.generation
 -------------------------
 
+.. currentmodule:: spikeinterface.generation
+
 Core
 ~~~~
-.. automodule:: spikeinterface.generation
-
-    .. autofunction:: generate_recording
-    .. autofunction:: generate_sorting
-    .. autofunction:: generate_snippets
-    .. autofunction:: generate_templates
-    .. autofunction:: generate_recording_by_size
-    .. autofunction:: generate_ground_truth_recording
-    .. autofunction:: add_synchrony_to_sorting
-    .. autofunction:: synthesize_random_firings
-    .. autofunction:: inject_some_duplicate_units
-    .. autofunction:: inject_some_split_units
-    .. autofunction:: synthetize_spike_train_bad_isi
-    .. autofunction:: inject_templates
-    .. autofunction:: noise_generator_recording
-    .. autoclass:: InjectTemplatesRecording
-    .. autoclass:: NoiseGeneratorRecording
+
+
+.. autofunction:: generate_recording
+.. autofunction:: generate_sorting
+.. autofunction:: generate_snippets
+.. autofunction:: generate_templates
+.. autofunction:: generate_recording_by_size
+.. autofunction:: generate_ground_truth_recording
+.. autofunction:: add_synchrony_to_sorting
+.. autofunction:: synthesize_random_firings
+.. autofunction:: inject_some_duplicate_units
+.. autofunction:: inject_some_split_units
+.. autofunction:: synthetize_spike_train_bad_isi
+.. autofunction:: inject_templates
+.. autofunction:: noise_generator_recording
+.. autoclass:: InjectTemplatesRecording
+.. autoclass:: NoiseGeneratorRecording
 
 Drift
 ~~~~~
-.. automodule:: spikeinterface.generation
 
-    .. autofunction:: generate_drifting_recording
-    .. autofunction:: generate_displacement_vector
-    .. autofunction:: make_one_displacement_vector
-    .. autofunction:: make_linear_displacement
-    .. autofunction:: move_dense_templates
-    .. autofunction:: interpolate_templates
-    .. autoclass:: DriftingTemplates
-    .. autoclass:: InjectDriftingTemplatesRecording
+.. autofunction:: generate_drifting_recording
+.. autofunction:: generate_displacement_vector
+.. autofunction:: make_one_displacement_vector
+.. autofunction:: make_linear_displacement
+.. autofunction:: move_dense_templates
+.. autofunction:: interpolate_templates
+.. autoclass:: DriftingTemplates
+.. autoclass:: InjectDriftingTemplatesRecording
 
 Hybrid
 ~~~~~~
-.. automodule:: spikeinterface.generation
 
-    .. autofunction:: generate_hybrid_recording
-    .. autofunction:: estimate_templates_from_recording
-    .. autofunction:: select_templates
-    .. autofunction:: scale_template_to_range
-    .. autofunction:: relocate_templates
-    .. autofunction:: fetch_template_object_from_database
-    .. autofunction:: fetch_templates_database_info
-    .. autofunction:: list_available_datasets_in_template_database
-    .. autofunction:: query_templates_from_database
+.. autofunction:: generate_hybrid_recording
+.. autofunction:: estimate_templates_from_recording
+.. autofunction:: select_templates
+.. autofunction:: scale_template_to_range
+.. autofunction:: relocate_templates
+.. autofunction:: fetch_template_object_from_database
+.. autofunction:: fetch_templates_database_info
+.. autofunction:: list_available_datasets_in_template_database
+.. autofunction:: query_templates_from_database
 
 
 Noise
 ~~~~~
-.. automodule:: spikeinterface.generation
 
-    .. autofunction:: generate_noise
+.. autofunction:: generate_noise
 
 
 spikeinterface.sortingcomponents

doc/conf.py

@@ -74,6 +74,8 @@
     "IPython.sphinxext.ipython_console_highlighting"
 ]
 
+autosectionlabel_prefix_document = True
+
 numpydoc_show_class_members = False
 
 
@@ -128,7 +130,7 @@
                                        '../examples/tutorials/widgets',
                                        ]),
     'within_subsection_order': FileNameSortKey,
-    'ignore_pattern': '/generate_',
+    'ignore_pattern': '/generate_*',
     'nested_sections': False,
     'copyfile_regex': r'.*\.rst|.*\.png|.*\.svg'
 }

doc/get_started/install_sorters.rst

@@ -27,7 +27,7 @@ sorters to retrieve installation instructions for other operating systems.
 We use **pip** to install packages, but **conda** should also work in many cases.
 
 Some novel spike sorting algorithms are implemented directly in SpikeInterface using the
-:py:mod:`spikeinterface.sortingcomponents` module. Checkout the :ref:`SpikeInterface-based spike sorters` section of this page
+:py:mod:`spikeinterface.sortingcomponents` module. Checkout the :ref:`get_started/install_sorters:SpikeInterface-based spike sorters` section of this page
 for more information!
 
 If you experience installation problems please directly contact the authors of these tools or write on the

doc/get_started/installation.rst

@@ -102,4 +102,4 @@ Sub-modules have more dependencies, so you should also install:
 
 
 All external spike sorters can be either run inside containers (Docker or Singularity - see :ref:`containerizedsorters`)
-or must be installed independently (see :ref:`Installing Spike Sorters`).
+or must be installed independently (see :ref:`get_started/install_sorters:Installing Spike Sorters`).

doc/how_to/load_your_data_into_sorting.rst

@@ -18,7 +18,7 @@ to take your existing data and load it as a SpikeInterface :code:`Sorting` objec
 
 
 Reading a standard spike sorting format into a :code:`Sorting`
--------------------------------------------------------------
+--------------------------------------------------------------
 
 For most spike sorting output formats the :code:`Sorting` is automatically generated. For example one could do
 
@@ -36,7 +36,7 @@ current formats see :ref:`compatible_formats`.
 
 
 Loading your own data into a :code:`Sorting`
--------------------------------------------
+--------------------------------------------
 
 
 This :code:`Sorting` contains important information about your spike trains including:
@@ -115,7 +115,7 @@ using :code:`Neo.SpikeTrain`'s.
 
 
 Loading multisegment data into a :code:`Sorting`
------------------------------------------------
+------------------------------------------------
 
 One of the great advantages of SpikeInterface :code:`Sorting` objects is that they can also handle
 multisegment recordings and sortings (e.g. you have a baseline, stimulus, post-stimulus). The

doc/index.rst

@@ -12,15 +12,13 @@ SpikeInterface is a Python module to analyze extracellular electrophysiology dat
 With a few lines of code, SpikeInterface enables you to load and pre-process the recording, run several
 state-of-the-art spike sorters, post-process and curate the output, compute quality metrics, and visualize the results.
 
-
 .. warning::
 
-    **New features under construction!** 🚧🚧🚧: after the 0.100.0 release (and related bug fixes), the next release will contain
     a major API improvement: the :code:`SortingAnalyzer`. To read more about this, checkout the
     `enhancement proposal <https://github.com/SpikeInterface/spikeinterface/issues/2282>`_.
-    Please refer to the stable documentation `here <https://spikeinterface.readthedocs.io/en/0.100.4>`_.
-    Learn how to update your code `here <tutorials/waveform_extractor_to_sorting_analyzer.html>`_ and read more about the
-    :code:`SortingAnalyzer` `here <modules/postprocessing.html>`_.
+    Please refer to the `stable documentation <https://spikeinterface.readthedocs.io/en/0.100.4>`_.
+    Learn how to :ref:`update your code here <tutorials/waveform_extractor_to_sorting_analyzer:From WaveformExtractor to SortingAnalyzer>` and read more about the
+    :ref:`SortingAnalyzer here <modules/postprocessing:Postprocessing module>`.
 
 
 

doc/modules/core.rst

@@ -21,7 +21,7 @@ All classes support:
   * data on-demand (lazy loading)
   * multiple segments, where each segment is a contiguous piece of data (recording, sorting, events).
 
-.. _core-recording:
+
 Recording
 ---------
 
@@ -162,7 +162,6 @@ Internally, any sorting object can construct 2 internal caches:
   2. a unique numpy.array with structured dtype aka "spikes vector". This is useful for processing by small chunks of
      time, like for extracting amplitudes from a recording.
 
-.. _core-sorting-analyzer:
 SortingAnalyzer
 ---------------
 
@@ -178,7 +177,7 @@ to perform further analysis, such as calculating :code:`waveforms` and :code:`te
 
 Importantly, the :py:class:`~spikeinterface.core.SortingAnalyzer` handles the *sparsity* and the physical *scaling*.
 Sparsity defines the channels on which waveforms and templates are calculated using, for example,  a
-physical distance from the channel with the largest peak amplitude (see the :ref:`Sparsity` section). Scaling, set by
+physical distance from the channel with the largest peak amplitude (see the :ref:`modules/core:Sparsity` section). Scaling, set by
 the :code:`return_scaled` argument, determines whether the data is converted from integer values to :math:`\mu V` or not.
 By default, :code:`return_scaled` is true and all processed data voltage values are in :math:`\mu V` (e.g., waveforms, templates, spike amplitudes, etc.).
 
@@ -207,7 +206,7 @@ Now we will create a :code:`SortingAnalyzer` called :code:`sorting_analyzer`.
 The :py:class:`~spikeinterface.core.SortingAnalyzer` by default is defined *in memory*, but it can be saved at any time
 (or upon instantiation) to one of the following backends:
 
-* | :code:`zarr`: the sorting analyzer is saved to a `Zarr <https://zarr.dev/>`_  folder, and each extension is a Zarr group. This is the recommended backend, since Zarr files can be written to/read from the cloud and compression is applied.
+* | :code:`zarr`: the sorting analyzer is saved to a `Zarr <https://zarr.dev/>`__  folder, and each extension is a Zarr group. This is the recommended backend, since Zarr files can be written to/read from the cloud and compression is applied.
 * | :code:`binary_folder`: the sorting analyzer is saved to a folder, and each extension creates a sub-folder. The extension data are saved to either :code:`npy` (for arrays), :code:`csv` (for dataframes), or :code:`pickle` (for everything else).
 
 If the sorting analyzer is in memory, the :code:`SortingAnalyzer.save_as` function can be used to save it
@@ -568,7 +567,7 @@ re-instantiate the object from scratch (this is true for all objects except in-m
 
 The :code:`save()` function allows to easily store SI objects to a folder on disk.
 :py:class:`~spikeinterface.core.BaseRecording` objects are stored in binary (.raw) or
-`Zarr <https://zarr.readthedocs.io/en/stable/tutorial.html>`_ (.zarr) format and
+`Zarr <https://zarr.readthedocs.io/en/stable/tutorial.html>`__ (.zarr) format and
 :py:class:`~spikeinterface.core.BaseSorting` and :py:class:`~spikeinterface.core.BaseSnippets` object in numpy (.npz)
 format. With the actual data, the :code:`save()` function also stores the provenance dictionary and all the properties
 and annotations associated to the object.
@@ -922,7 +921,7 @@ The :py:class:`~spikeinterface.core.WaveformExtractor` allows us to:
 * extract waveforms
 * sub-sample spikes for waveform extraction
 * compute templates (i.e. average extracellular waveforms) with different modes
-* save waveforms in a folder (in numpy / `Zarr <https://zarr.readthedocs.io/en/stable/tutorial.html>`_) for easy retrieval
+* save waveforms in a folder (in numpy / `Zarr <https://zarr.readthedocs.io/en/stable/tutorial.html>`__) for easy retrieval
 * save sparse waveforms or *sparsify* dense waveforms
 * select units and associated waveforms
 

doc/modules/curation.rst

@@ -65,12 +65,12 @@ This format has two part:
     * "merged_unit_groups"
     * "removed_units"
 
-Here is the description of the format with a simple example:
+Here is the description of the format with a simple example (the first part of the
+format is the definition; the second part of the format is manual action):
 
 .. code-block:: json
 
     {
-        # the first part of the format is the definitation
         "format_version": "1",
         "unit_ids": [
             "u1",
@@ -91,7 +91,7 @@ Here is the description of the format with a simple example:
                     "MUA",
                     "artifact"
                 ],
-                "exclusive": true
+                "exclusive": "true"
             },
             "putative_type": {
                 "label_options": [
@@ -100,10 +100,10 @@ Here is the description of the format with a simple example:
                     "pyramidal",
                     "mitral"
                 ],
-                "exclusive": false
+                "exclusive": "false"
             }
         },
-        # the second part of the format is manual action
+
         "manual_labels": [
             {
                 "unit_id": "u1",

doc/modules/exporters.rst

@@ -15,7 +15,7 @@ results.
 **Note** : :py:func:`~spikeinterface.exporters.export_to_phy` speed and the size of the folder will highly depend
 on the sparsity of the :code:`SortingAnalyzer` itself or the external specified sparsity.
 The Phy viewer enables one to explore PCA projections, spike amplitudes, waveforms and quality of spike sorting results.
-So if these pieces of information have already been computed as extensions (see :ref:`analyzer_extensions`),
+So if these pieces of information have already been computed as extensions (see :ref:`modules/postprocessing:Extensions as AnalyzerExtensions`),
 then exporting to Phy should be fast (and the user has better control of the parameters for the extensions).
 If not pre-computed, then the required extensions (e.g., :code:`spike_amplitudes`, :code:`principal_components`)
 can be computed directly at export time.

doc/modules/postprocessing.rst

@@ -59,7 +59,7 @@ To check what extensions spikeinterface can calculate, you can use the :code:`ge
 
     >>> ['random_spikes', 'waveforms', 'templates', 'noise_levels', 'amplitude_scalings', 'correlograms', 'isi_histograms', 'principal_components', 'spike_amplitudes', 'spike_locations', 'template_metrics', 'template_similarity', 'unit_locations', 'quality_metrics']
 
-There is detailed documentation about each extension :ref:`below<Available postprocessing extensions>`.
+There is detailed documentation about each extension :ref:`below<modules/postprocessing:Available postprocessing extensions>`.
 Each extension comes from a different module. To use the :code:`postprocessing` extensions, you'll need to have the `postprocessing`
 module loaded.
 
@@ -68,11 +68,9 @@ both `random_spikes` and `waveforms`. We say that `principal_components` is a ch
 two. Other extensions, like `isi_histograms`, don't depend on anything. It has no children and no parents. The parent/child
 relationships of all the extensions currently defined in spikeinterface can be found in this diagram:
 
-|
 .. figure:: ../images/parent_child.svg
     :alt: Parent child relationships for the extensions in spikeinterface
     :align: center
-|
 
 If you try to calculate a child before calculating a parent, an error will be thrown. Further, when a parent is recalculated we delete
 its children. Why? Consider calculating :code:`principal_components`. This depends on random selection of spikes chosen
@@ -312,7 +310,7 @@ By default, the following metrics are computed:
 The units of :code:`recovery_slope` and :code:`repolarization_slope` depend on the
 input. Voltages are based on the units of the template. By default this is :math:`\mu V`
 but can be the raw output from the recording device (this depends on the
-:code:`return_scaled` parameter, read more here: :ref:`core-sorting-analyzer`).
+:code:`return_scaled` parameter, read more here: :ref:`modules/core:SortingAnalyzer`).
 Distances are in :math:`\mu m` and times are in seconds. So, for example, if the
 templates are in units of :math:`\mu V` then: :code:`repolarization_slope` is in
 :math:`mV / s`; :code:`peak_to_trough_ratio` is in :math:`\mu m` and the