Reorganising documentation into Getting Started, Tutorial and How To (#…

…2778)

* Reorganising documentation into Getting Started, Tutorial and How To #2778

.gitignore

@@ -38,15 +38,6 @@ spikeinterface/sorters/tests/*/*
 
 spikeinterface/widgets/tests/mearec_test/*
 
-
-examples/modules_gallery/**/*.raw
-examples/modules_gallery/**/*.npy
-examples/modules_gallery/**/*.json
-examples/modules_gallery/**/*.pkl
-examples/modules_gallery/**/*.npz
-examples/modules_gallery/**/*.csv
-
-
 .vscode/*
 
 # MauroToro: My absolute mess of envs
@@ -166,8 +157,19 @@ venv.bak/
 # mypy
 .mypy_cache/
 
+# documentation files
+
+examples/tutorials/**/*.raw
+examples/tutorials/**/*.npy
+examples/tutorials/**/*.json
+examples/tutorials/**/*.pkl
+examples/tutorials/**/*.npz
+examples/tutorials/**/*.csv
+examples/tutorials/*.png
+examples/tutorials/*.svg
+
 doc/_build/*
-doc/modules_gallery/*
+doc/tutorials/*
 doc/sources/*
 
 examples/getting_started/tmp_*

doc/conf.py

@@ -29,17 +29,17 @@
 
 # clean some folder
 folders =  [
-    '../examples/modules_gallery/core/my_recording',
-    '../examples/modules_gallery/core/my_sorting',
-    '../examples/modules_gallery/core/waveform_folder',
-    '../examples/modules_gallery/core/waveform_folder_parallel',
-    '../examples/modules_gallery/core/waveform_folder_sparse',
-    '../examples/modules_gallery/core/waveform_folder_sparse_direct',
-    '../examples/modules_gallery/core/waveform_folder2',
-    '../examples/modules_gallery/core/waveform_folder',
-    '../examples/modules_gallery/qualitymetrics/waveforms_mearec',
-    '../examples/modules_gallery/qualitymetrics/wfs_mearec',
-    '../examples/modules_gallery/widgets/waveforms_mearec',
+    '../examples/tutorials/core/my_recording',
+    '../examples/tutorials/core/my_sorting',
+    '../examples/tutorials/core/waveform_folder',
+    '../examples/tutorials/core/waveform_folder_parallel',
+    '../examples/tutorials/core/waveform_folder_sparse',
+    '../examples/tutorials/core/waveform_folder_sparse_direct',
+    '../examples/tutorials/core/waveform_folder2',
+    '../examples/tutorials/core/waveform_folder',
+    '../examples/tutorials/qualitymetrics/waveforms_mearec',
+    '../examples/tutorials/qualitymetrics/wfs_mearec',
+    '../examples/tutorials/widgets/waveforms_mearec',
 
 ]
 
@@ -63,9 +63,9 @@
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
-    'sphinx.ext.autosectionlabel',
     'sphinx_gallery.gen_gallery',
     'numpydoc',
+    'sphinx.ext.autosectionlabel',
     'sphinx_design',
     "sphinx.ext.intersphinx",
     "sphinx.ext.extlinks",
@@ -117,18 +117,19 @@
 # for sphinx gallery plugin
 sphinx_gallery_conf = {
     'only_warn_on_example_error': True,
-    'examples_dirs': ['../examples/modules_gallery'],
-    'gallery_dirs': ['modules_gallery', ],  # path where to save gallery generated examples
+    'examples_dirs': ['../examples/tutorials'],
+    'gallery_dirs': ['tutorials' ],  # path where to save gallery generated examples
     'subsection_order': ExplicitOrder([
-                                       '../examples/modules_gallery/core',
-                                       '../examples/modules_gallery/extractors',
-                                       '../examples/modules_gallery/qualitymetrics',
-                                       '../examples/modules_gallery/comparison',
-                                       '../examples/modules_gallery/widgets',
+                                       '../examples/tutorials/core',
+                                       '../examples/tutorials/extractors',
+                                       '../examples/tutorials/qualitymetrics',
+                                       '../examples/tutorials/comparison',
+                                       '../examples/tutorials/widgets',
                                        ]),
     'within_subsection_order': FileNameSortKey,
     'ignore_pattern': '/generate_',
     'nested_sections': False,
+    'copyfile_regex': r'.*\.rst|.*\.png|.*\.svg'
 }
 
 intersphinx_mapping = {

doc/get_started/index.rst

@@ -0,0 +1,12 @@
+Getting started
+===============
+
+How to get started using spikeinterface. Also check out spike tutorials!
+
+.. toctree::
+    :maxdepth: 1
+
+    installation
+    quickstart
+    import
+    install_sorters

doc/install_sorters.rst → doc/get_started/install_sorters.rst

@@ -1,5 +1,3 @@
-.. _installsorters:
-
 Installing Spike Sorters
 ========================
 
@@ -29,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:`si_based` section of this page
+:py:mod:`spikeinterface.sortingcomponents` module. Checkout the :ref:`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
@@ -262,11 +260,6 @@ Combinato
       # provide installation path by setting the COMBINATO_PATH environment variable
       # or using CombinatoSorter.set_combinato_path()
 
-
-
-
-.. _si_based:
-
 SpikeInterface-based spike sorters
 ----------------------------------
 

doc/installation.rst → 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:`installsorters`).
+or must be installed independently (see :ref:`Installing Spike Sorters`).