From f34da1aff682828dfba78cd17034c0fc2cb40fda Mon Sep 17 00:00:00 2001 From: JoeZiminski Date: Fri, 1 Nov 2024 14:03:13 +0000 Subject: [PATCH 1/2] Make new index page with hover CSS. --- doc/_static/css/custom.css | 20 +++ doc/conf.py | 6 +- doc/index.rst | 1 + doc/tutorials_custom_index.rst | 254 +++++++++++++++++++++++++++++++++ 4 files changed, 279 insertions(+), 2 deletions(-) create mode 100644 doc/_static/css/custom.css create mode 100644 doc/tutorials_custom_index.rst diff --git a/doc/_static/css/custom.css b/doc/_static/css/custom.css new file mode 100644 index 0000000000..0c51da539e --- /dev/null +++ b/doc/_static/css/custom.css @@ -0,0 +1,20 @@ +/* Center and make the title bold */ +.gallery-card .grid-item-card-title { + text-align: center; + font-weight: bold; +} + +/* Default style for hover content (hidden) */ +.gallery-card .hover-content { + display: none; + text-align: center; +} + +/* Show the hover content when hovering over the card */ +.gallery-card:hover .default-title { + display: none; +} + +.gallery-card:hover .hover-content { + display: block; +} diff --git a/doc/conf.py b/doc/conf.py index e3d58ca8f2..db16269991 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -109,8 +109,10 @@ # 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". -# html_static_path = ['_static'] - +html_static_path = ['_static'] +html_css_files = [ + 'css/custom.css', +] html_favicon = "images/favicon-32x32.png" diff --git a/doc/index.rst b/doc/index.rst index ed443e4200..57a0c95443 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -51,6 +51,7 @@ SpikeInterface is made of several modules to deal with different aspects of the overview get_started/index + tutorials_custom_index tutorials/index how_to/index modules/index diff --git a/doc/tutorials_custom_index.rst b/doc/tutorials_custom_index.rst new file mode 100644 index 0000000000..46a7bea630 --- /dev/null +++ b/doc/tutorials_custom_index.rst @@ -0,0 +1,254 @@ +.. This page provides a custom index to the 'Tutorials' page, rather than the default sphinx-gallery +.. generated page. The benefits of this are flexibility in design and inclusion of non-sphinx files in the index. +.. +.. To update this index with a new documentation page +.. 1) Copy the grid-item-card and associated ".. raw:: html" section. +.. 2) change :link: to a link to your page. If this is an `.rst` file, point to the rst file directly. +.. If it is a sphinx-gallery generated file, format the path as separated by underscore and prefix `sphx_glr`, +.. pointing to the .py file. e.g. `tutorials/my/page.py` -> `sphx_glr_tutorials_my_page.py +.. 3) Change :img-top: to point to the thumbnail image of your choosing. You can point to images generated +.. in the sphinx gallery page if you wish. +.. 4) In the `html` section, change the `default-title` to your pages title and `hover-content` to the subtitle. + +:orphan: + +TutorialsNew +============ + +Longer form tutorials about using SpikeInterface. Many of these are downloadable as notebooks or Python scripts so that you can "code along" with the tutorials. + +If you're new to SpikeInterface, we recommend trying out the :ref:`get_started/quickstart:Quickstart tutorial` first. + +Updating from legacy +-------------------- + +.. toctree:: + :maxdepth: 1 + + tutorials/waveform_extractor_to_sorting_analyzer + +Core tutorials +-------------- + +These tutorials focus on the :py:mod:`spikeinterface.core` module. + +.. grid:: 1 2 2 3 + :gutter: 2 + + .. grid-item-card:: + :link-type: ref + :link: sphx_glr_tutorials_core_plot_1_recording_extractor.py + :img-top: /tutorials/core/images/thumb/sphx_glr_plot_1_recording_extractor_thumb.png + :img-alt: Recording objects + :class-card: gallery-card + + .. raw:: html + +
Recording objects
+
Manage loaded recordings in SpikeInterface
+ + .. grid-item-card:: + :link-type: ref + :link: sphx_glr_tutorials_core_plot_2_sorting_extractor.py + :img-top: /tutorials/core/images/thumb/sphx_glr_plot_2_sorting_extractor_thumb.png + :img-alt: Sorting objects + :class-card: gallery-card + + .. raw:: html + +
Sorting objects
+
Explore sorting extractor features
+ + .. grid-item-card:: + :link-type: ref + :link: sphx_glr_tutorials_core_plot_3_handle_probe_info.py + :img-top: /tutorials/core/images/thumb/sphx_glr_plot_3_handle_probe_info_thumb.png + :img-alt: Handling probe information + :class-card: gallery-card + + .. raw:: html + +
Handling probe information
+
Handle and visualize probe information
+ + .. grid-item-card:: + :link-type: ref + :link: sphx_glr_tutorials_core_plot_4_sorting_analyzer.py + :img-top: /tutorials/core/images/thumb/sphx_glr_plot_4_sorting_analyzer_thumb.png + :img-alt: SortingAnalyzer + :class-card: gallery-card + + .. raw:: html + +
SortingAnalyzer
+
Analyze sorting results with ease
+ + .. grid-item-card:: + :link-type: ref + :link: sphx_glr_tutorials_core_plot_5_append_concatenate_segments.py + :img-top: /tutorials/core/images/thumb/sphx_glr_plot_5_append_concatenate_segments_thumb.png + :img-alt: Append/Concatenate segments + :class-card: gallery-card + + .. raw:: html + +
Append and/or concatenate segments
+
Combine segments efficiently
+ + .. grid-item-card:: + :link-type: ref + :link: sphx_glr_tutorials_core_plot_6_handle_times.py + :img-top: /tutorials/core/images/thumb/sphx_glr_plot_6_handle_times_thumb.png + :img-alt: Handle time information + :class-card: gallery-card + + .. raw:: html + +
Handle time information
+
Manage and analyze time information
+ +Extractors tutorials +-------------------- + +The :py:mod:`spikeinterface.extractors` module is designed to load and save recorded and sorted data, and to handle probe information. + +.. grid:: 1 2 2 3 + :gutter: 2 + + .. grid-item-card:: + :link-type: ref + :link: sphx_glr_tutorials_extractors_plot_1_read_various_formats.py + :img-top: /tutorials/extractors/images/thumb/sphx_glr_plot_1_read_various_formats_thumb.png + :img-alt: Read various formats + :class-card: gallery-card + + .. raw:: html + +
Read various formats
+
Read different recording formats efficiently
+ + .. grid-item-card:: + :link-type: ref + :link: sphx_glr_tutorials_extractors_plot_2_working_with_unscaled_traces.py + :img-top: /tutorials/extractors/images/thumb/sphx_glr_plot_2_working_with_unscaled_traces_thumb.png + :img-alt: Unscaled traces + :class-card: gallery-card + + .. raw:: html + +
Working with unscaled traces
+
Learn about managing unscaled traces
+ +Quality metrics tutorial +------------------------ + +The :code:`spikeinterface.qualitymetrics` module allows users to compute various quality metrics to assess the goodness of a spike sorting output. + +.. grid:: 1 2 2 3 + :gutter: 2 + + .. grid-item-card:: + :link-type: ref + :link: sphx_glr_tutorials_qualitymetrics_plot_3_quality_mertics.py + :img-top: /tutorials/qualitymetrics/images/thumb/sphx_glr_plot_3_quality_mertics_thumb.png + :img-alt: Quality Metrics + :class-card: gallery-card + + .. raw:: html + +
Quality Metrics
+
Evaluate sorting quality using metrics
+ + .. grid-item-card:: + :link-type: ref + :link: sphx_glr_tutorials_qualitymetrics_plot_4_curation.py + :img-top: /tutorials/qualitymetrics/images/thumb/sphx_glr_plot_4_curation_thumb.png + :img-alt: Curation Tutorial + :class-card: gallery-card + + .. raw:: html + +
Curation Tutorial
+
Learn how to curate spike sorting data
+ +Comparison tutorial +------------------- + +The :code:`spikeinterface.comparison` module allows you to compare sorter outputs or benchmark against ground truth. + +.. grid:: 1 2 2 3 + :gutter: 2 + + .. grid-item-card:: + :link-type: ref + :link: sphx_glr_tutorials_comparison_plot_5_comparison_sorter_weaknesses.py + :img-top: /tutorials/comparison/images/thumb/sphx_glr_plot_5_comparison_sorter_weaknesses_thumb.png + :img-alt: Sorter Comparison + :class-card: gallery-card + + .. raw:: html + +
Sorter Comparison
+
Compare sorter outputs and assess weaknesses
+ +Widgets tutorials +----------------- + +The :code:`widgets` module contains several plotting routines (widgets) for visualizing recordings, sorting data, probe layout, and more. + +.. grid:: 1 2 2 3 + :gutter: 2 + + .. grid-item-card:: + :link-type: ref + :link: sphx_glr_tutorials_widgets_plot_1_rec_gallery.py + :img-top: /tutorials/widgets/images/thumb/sphx_glr_plot_1_rec_gallery_thumb.png + :img-alt: Recording Widgets + :class-card: gallery-card + + .. raw:: html + +
RecordingExtractor Widgets
+
Visualize recordings with widgets
+ + .. grid-item-card:: + :link-type: ref + :link: sphx_glr_tutorials_widgets_plot_2_sort_gallery.py + :img-top: /tutorials/widgets/images/thumb/sphx_glr_plot_2_sort_gallery_thumb.png + :img-alt: Sorting Widgets + :class-card: gallery-card + + .. raw:: html + +
SortingExtractor Widgets
+
Explore sorting data using widgets
+ + .. grid-item-card:: + :link-type: ref + :link: sphx_glr_tutorials_widgets_plot_3_waveforms_gallery.py + :img-top: /tutorials/widgets/images/thumb/sphx_glr_plot_3_waveforms_gallery_thumb.png + :img-alt: Waveforms Widgets + :class-card: gallery-card + + .. raw:: html + +
Waveforms Widgets
+
Display waveforms using SpikeInterface
+ + .. grid-item-card:: + :link-type: ref + :link: sphx_glr_tutorials_widgets_plot_4_peaks_gallery.py + :img-top: /tutorials/widgets/images/thumb/sphx_glr_plot_4_peaks_gallery_thumb.png + :img-alt: Peaks Widgets + :class-card: gallery-card + + .. raw:: html + +
Peaks Widgets
+
Visualize detected peaks
+ +Download All Examples +--------------------- + +- :download:`Download all examples in Python source code ` +- :download:`Download all examples in Jupyter notebooks ` From 7aa93490cca20916338629518800a1cbf976b8ff Mon Sep 17 00:00:00 2001 From: JoeZiminski Date: Fri, 1 Nov 2024 14:53:22 +0000 Subject: [PATCH 2/2] Remove CSS and update development docs. --- doc/_static/css/custom.css | 20 ----- doc/conf.py | 6 +- doc/development/development.rst | 19 +++++ doc/index.rst | 1 - doc/tutorials_custom_index.rst | 128 +++++++++----------------------- 5 files changed, 56 insertions(+), 118 deletions(-) delete mode 100644 doc/_static/css/custom.css diff --git a/doc/_static/css/custom.css b/doc/_static/css/custom.css deleted file mode 100644 index 0c51da539e..0000000000 --- a/doc/_static/css/custom.css +++ /dev/null @@ -1,20 +0,0 @@ -/* Center and make the title bold */ -.gallery-card .grid-item-card-title { - text-align: center; - font-weight: bold; -} - -/* Default style for hover content (hidden) */ -.gallery-card .hover-content { - display: none; - text-align: center; -} - -/* Show the hover content when hovering over the card */ -.gallery-card:hover .default-title { - display: none; -} - -.gallery-card:hover .hover-content { - display: block; -} diff --git a/doc/conf.py b/doc/conf.py index db16269991..e3d58ca8f2 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -109,10 +109,8 @@ # 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". -html_static_path = ['_static'] -html_css_files = [ - 'css/custom.css', -] +# html_static_path = ['_static'] + html_favicon = "images/favicon-32x32.png" diff --git a/doc/development/development.rst b/doc/development/development.rst index a91818a271..1638c41243 100644 --- a/doc/development/development.rst +++ b/doc/development/development.rst @@ -213,6 +213,25 @@ We use Sphinx to build the documentation. To build the documentation locally, yo This will build the documentation in the :code:`doc/_build/html` folder. You can open the :code:`index.html` file in your browser to see the documentation. +Adding new documentation +------------------------ + +Documentation can be added as a +`sphinx-gallery `_ +python file ('tutorials') +or a +`sphinx rst `_ +file (all other sections). + +To add a new tutorial, add your ``.py`` file to ``spikeinterface/examples``. +Then, update the ``spikeinterface/doc/tutorials_custom_index.rst`` file +to make a new card linking to the page and an optional image. See +``tutorials_custom_index.rst`` header for more information. + +For other sections, write your documentation in ``.rst`` format and add +the page to the appropriate ``index.rst`` file found in the relevant +folder (e.g. ``how_to/index.rst``). + How to run code coverage locally -------------------------------- To run code coverage locally, you can use the following command: diff --git a/doc/index.rst b/doc/index.rst index 57a0c95443..e6d8aa3fea 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -52,7 +52,6 @@ SpikeInterface is made of several modules to deal with different aspects of the overview get_started/index tutorials_custom_index - tutorials/index how_to/index modules/index api diff --git a/doc/tutorials_custom_index.rst b/doc/tutorials_custom_index.rst index 46a7bea630..4c7625d811 100644 --- a/doc/tutorials_custom_index.rst +++ b/doc/tutorials_custom_index.rst @@ -12,12 +12,14 @@ :orphan: -TutorialsNew +Tutorials ============ -Longer form tutorials about using SpikeInterface. Many of these are downloadable as notebooks or Python scripts so that you can "code along" with the tutorials. +Longer form tutorials about using SpikeInterface. Many of these are downloadable +as notebooks or Python scripts so that you can "code along" with the tutorials. -If you're new to SpikeInterface, we recommend trying out the :ref:`get_started/quickstart:Quickstart tutorial` first. +If you're new to SpikeInterface, we recommend trying out the +:ref:`get_started/quickstart:Quickstart tutorial` first. Updating from legacy -------------------- @@ -35,77 +37,53 @@ These tutorials focus on the :py:mod:`spikeinterface.core` module. .. grid:: 1 2 2 3 :gutter: 2 - .. grid-item-card:: + .. grid-item-card:: Recording objects :link-type: ref :link: sphx_glr_tutorials_core_plot_1_recording_extractor.py :img-top: /tutorials/core/images/thumb/sphx_glr_plot_1_recording_extractor_thumb.png :img-alt: Recording objects :class-card: gallery-card + :text-align: center - .. raw:: html - -
Recording objects
-
Manage loaded recordings in SpikeInterface
- - .. grid-item-card:: + .. grid-item-card:: Sorting objects :link-type: ref :link: sphx_glr_tutorials_core_plot_2_sorting_extractor.py :img-top: /tutorials/core/images/thumb/sphx_glr_plot_2_sorting_extractor_thumb.png :img-alt: Sorting objects :class-card: gallery-card + :text-align: center - .. raw:: html - -
Sorting objects
-
Explore sorting extractor features
- - .. grid-item-card:: + .. grid-item-card:: Handling probe information :link-type: ref :link: sphx_glr_tutorials_core_plot_3_handle_probe_info.py :img-top: /tutorials/core/images/thumb/sphx_glr_plot_3_handle_probe_info_thumb.png :img-alt: Handling probe information :class-card: gallery-card + :text-align: center - .. raw:: html - -
Handling probe information
-
Handle and visualize probe information
- - .. grid-item-card:: + .. grid-item-card:: SortingAnalyzer :link-type: ref :link: sphx_glr_tutorials_core_plot_4_sorting_analyzer.py :img-top: /tutorials/core/images/thumb/sphx_glr_plot_4_sorting_analyzer_thumb.png :img-alt: SortingAnalyzer :class-card: gallery-card + :text-align: center - .. raw:: html - -
SortingAnalyzer
-
Analyze sorting results with ease
- - .. grid-item-card:: + .. grid-item-card:: Append and/or concatenate segments :link-type: ref :link: sphx_glr_tutorials_core_plot_5_append_concatenate_segments.py :img-top: /tutorials/core/images/thumb/sphx_glr_plot_5_append_concatenate_segments_thumb.png :img-alt: Append/Concatenate segments :class-card: gallery-card + :text-align: center - .. raw:: html - -
Append and/or concatenate segments
-
Combine segments efficiently
- - .. grid-item-card:: + .. grid-item-card:: Handle time information :link-type: ref :link: sphx_glr_tutorials_core_plot_6_handle_times.py :img-top: /tutorials/core/images/thumb/sphx_glr_plot_6_handle_times_thumb.png :img-alt: Handle time information :class-card: gallery-card - - .. raw:: html - -
Handle time information
-
Manage and analyze time information
+ :text-align: center Extractors tutorials -------------------- @@ -115,29 +93,21 @@ The :py:mod:`spikeinterface.extractors` module is designed to load and save reco .. grid:: 1 2 2 3 :gutter: 2 - .. grid-item-card:: + .. grid-item-card:: Read various formats :link-type: ref :link: sphx_glr_tutorials_extractors_plot_1_read_various_formats.py :img-top: /tutorials/extractors/images/thumb/sphx_glr_plot_1_read_various_formats_thumb.png :img-alt: Read various formats :class-card: gallery-card + :text-align: center - .. raw:: html - -
Read various formats
-
Read different recording formats efficiently
- - .. grid-item-card:: + .. grid-item-card:: Working with unscaled traces :link-type: ref :link: sphx_glr_tutorials_extractors_plot_2_working_with_unscaled_traces.py :img-top: /tutorials/extractors/images/thumb/sphx_glr_plot_2_working_with_unscaled_traces_thumb.png :img-alt: Unscaled traces :class-card: gallery-card - - .. raw:: html - -
Working with unscaled traces
-
Learn about managing unscaled traces
+ :text-align: center Quality metrics tutorial ------------------------ @@ -147,29 +117,21 @@ The :code:`spikeinterface.qualitymetrics` module allows users to compute various .. grid:: 1 2 2 3 :gutter: 2 - .. grid-item-card:: + .. grid-item-card:: Quality Metrics :link-type: ref :link: sphx_glr_tutorials_qualitymetrics_plot_3_quality_mertics.py :img-top: /tutorials/qualitymetrics/images/thumb/sphx_glr_plot_3_quality_mertics_thumb.png :img-alt: Quality Metrics :class-card: gallery-card + :text-align: center - .. raw:: html - -
Quality Metrics
-
Evaluate sorting quality using metrics
- - .. grid-item-card:: + .. grid-item-card:: Curation Tutorial :link-type: ref :link: sphx_glr_tutorials_qualitymetrics_plot_4_curation.py :img-top: /tutorials/qualitymetrics/images/thumb/sphx_glr_plot_4_curation_thumb.png :img-alt: Curation Tutorial :class-card: gallery-card - - .. raw:: html - -
Curation Tutorial
-
Learn how to curate spike sorting data
+ :text-align: center Comparison tutorial ------------------- @@ -179,17 +141,13 @@ The :code:`spikeinterface.comparison` module allows you to compare sorter output .. grid:: 1 2 2 3 :gutter: 2 - .. grid-item-card:: + .. grid-item-card:: Sorter Comparison :link-type: ref :link: sphx_glr_tutorials_comparison_plot_5_comparison_sorter_weaknesses.py :img-top: /tutorials/comparison/images/thumb/sphx_glr_plot_5_comparison_sorter_weaknesses_thumb.png :img-alt: Sorter Comparison :class-card: gallery-card - - .. raw:: html - -
Sorter Comparison
-
Compare sorter outputs and assess weaknesses
+ :text-align: center Widgets tutorials ----------------- @@ -199,53 +157,37 @@ The :code:`widgets` module contains several plotting routines (widgets) for visu .. grid:: 1 2 2 3 :gutter: 2 - .. grid-item-card:: + .. grid-item-card:: RecordingExtractor Widgets :link-type: ref :link: sphx_glr_tutorials_widgets_plot_1_rec_gallery.py :img-top: /tutorials/widgets/images/thumb/sphx_glr_plot_1_rec_gallery_thumb.png :img-alt: Recording Widgets :class-card: gallery-card + :text-align: center - .. raw:: html - -
RecordingExtractor Widgets
-
Visualize recordings with widgets
- - .. grid-item-card:: + .. grid-item-card:: SortingExtractor Widgets :link-type: ref :link: sphx_glr_tutorials_widgets_plot_2_sort_gallery.py :img-top: /tutorials/widgets/images/thumb/sphx_glr_plot_2_sort_gallery_thumb.png :img-alt: Sorting Widgets :class-card: gallery-card + :text-align: center - .. raw:: html - -
SortingExtractor Widgets
-
Explore sorting data using widgets
- - .. grid-item-card:: + .. grid-item-card:: Waveforms Widgets :link-type: ref :link: sphx_glr_tutorials_widgets_plot_3_waveforms_gallery.py :img-top: /tutorials/widgets/images/thumb/sphx_glr_plot_3_waveforms_gallery_thumb.png :img-alt: Waveforms Widgets :class-card: gallery-card + :text-align: center - .. raw:: html - -
Waveforms Widgets
-
Display waveforms using SpikeInterface
- - .. grid-item-card:: + .. grid-item-card:: Peaks Widgets :link-type: ref :link: sphx_glr_tutorials_widgets_plot_4_peaks_gallery.py :img-top: /tutorials/widgets/images/thumb/sphx_glr_plot_4_peaks_gallery_thumb.png :img-alt: Peaks Widgets :class-card: gallery-card - - .. raw:: html - -
Peaks Widgets
-
Visualize detected peaks
+ :text-align: center Download All Examples ---------------------