From 58c37bfb5cbb1644a0a45d2fc680e541f0baa279 Mon Sep 17 00:00:00 2001 From: Zach McKenzie <92116279+zm711@users.noreply.github.com> Date: Fri, 27 Oct 2023 20:55:41 -0400 Subject: [PATCH 1/6] add docstring section also fix some typos --- doc/development/development.rst | 77 ++++++++++++++++++++++++++------- 1 file changed, 62 insertions(+), 15 deletions(-) diff --git a/doc/development/development.rst b/doc/development/development.rst index 7656da11ab..71f3fb580d 100644 --- a/doc/development/development.rst +++ b/doc/development/development.rst @@ -50,7 +50,7 @@ If you want to run a specific test in a specific file, you can use the following .. code-block:: bash - pytest pytest src/spikeinterface/core/tests/test_baserecording.py::specific_test_in_this_module + pytest src/spikeinterface/core/tests/test_baserecording.py::specific_test_in_this_module We also mantain pytest markers to run specific tests. For example, if you want to run only the tests for the :code:`spikeinterface.extractors` module, you can use the following command: @@ -121,18 +121,18 @@ Stylistic conventions --------------------- -SpikeInterface maintains a consistent coding style across the project, leveraging the black Python code formatter. +SpikeInterface maintains a consistent coding style across the project, leveraging the Black Python code formatter. This helps to ensure readability and maintainability of the code, making it easier for contributors to collaborate. -To install black, you can use pip, the Python package installer. Run the following command in your terminal: +To install Black, you can use pip, the Python package installer. Run the following command in your terminal: .. code-block:: bash pip install black -This will install black into your current Python environment. +This will install Black into your current Python environment. -In addition to black, we use pre-commit to manage a suite of code formatting. +In addition to Black, we use pre-commit to manage a suite of code formatting. Pre-commit helps to automate the process of running these tools before every commit, ensuring that all code is checked for style. @@ -151,23 +151,70 @@ navigate to your local repository in your terminal and run the following command pre-commit install -Now, each time you make a commit, pre-commit will automatically run black and any other configured hooks. +Now, each time you make a commit, pre-commit will automatically run Black and any other configured hooks. If the hooks make changes or if there are any issues, the commit will be stopped, and you'll be able to review and add the changes. -If you want black to omit a line from formatting, you can add the following comment to the end of the line: +If you want Black to omit a line from formatting, you can add the following comment to the end of the line: + +.. code-block:: python + + # fmt: skip + +To ignore a block of code you must flank the code with two comments: .. code-block:: python # fmt: off + code here + # fmt: on As described in the `black documentation `_, -The following are some styling conventions that we follow in SpikeInterface: + +For docstrings, SpikeInterface generally follows `numpy docstring standard `_. +This includes providing a one line summary of a function, and the standard NumPy sections including :code:`Parameters`, :code:`Returns`, etc. The format used +for providing parameters, however is a little different. The project prefers the format: + +.. code-block:: bash + + parameter_name: type, default: default_value + + +This allows users to quickly understand the type of data that should be input into a function as well as whether a default is supplied. A full example would be: + +.. code-block:: python + + def a_function(param_a, param_b=5, param_c="mean"): + """ + A function for analyzing data + + Parameters + ---------- + param_a: dict + A dictionary containing the data + param_b: int, default: 5 + A scaling factor to be applied to the data + param_c: "mean" | "median", default: "mean" + What to calculate on the data + + Returns + ------- + great_data: dict + A dictionary of the processed data + """ + + +Note that in this example we demonstrate two other docstring conventions followed by SpikeInterface. First, that all string arguments should be presented +with double quotes. This is the same stylistic convention followed by Black and enforced by the pre-commit for the repo. Second, when a parameter is a +string with a limited number of values (e.g. :code:`mean` and :code:`median`), rather than give the type a value of :code:`str`, please list the possible strings +so that the user knows what the options are. + +The following are some additional styling conventions that we follow in SpikeInterface: #. Avoid using abreviations in variable names (e.g., use :code:`recording` instead of :code:`rec`). It is especially important to avoid single letter variables. -#. Use index as singular and indices for plural following Numpy. Avoid idx or indexes. Plus, id and ids are reserved for identifiers (i.e. channel_ids) +#. Use index as singular and indices for plural following the NumPy convention. Avoid idx or indexes. Plus, id and ids are reserved for identifiers (i.e. channel_ids) #. We use file_path and folder_path (instead of file_name and folder_name) for clarity. -#. Use the `numpy docstring standard `_ in all the docstrings. + How to build the documentation ------------------------------ @@ -199,14 +246,14 @@ Implement a new extractor ------------------------- SpikeInterface already supports over 30 file formats, but the acquisition system you use might not be among the -supported formats list (***ref***). Most of the extractord rely on the `NEO `_ +supported formats list (***ref***). Most of the extractors rely on the `NEO `_ package to read information from files. -Therefore, to implement a new extractor to handle the unsupported format, we recommend make a new :code:`neo.rawio.BaseRawIO` class (see `example `_). +Therefore, to implement a new extractor to handle the unsupported format, we recommend making a new :code:`neo.rawio.BaseRawIO` class (see `example `_). Once that is done, the new class can be easily wrapped into SpikeInterface as an extension of the :py:class:`~spikeinterface.extractors.neoextractors.neobaseextractors.NeoBaseRecordingExtractor` (for :py:class:`~spikeinterface.core.BaseRecording` objects) or :py:class:`~spikeinterface.extractors.neoextractors.neobaseextractors.NeoBaseRecordingExtractor` -(for py:class:`~spikeinterface.core.BaseSorting` objects) or with a few lines of +(for :py:class:`~spikeinterface.core.BaseSorting` objects) or with a few lines of code (e.g., see reader for `SpikeGLX `_ or `Neuralynx `_). @@ -345,9 +392,9 @@ Moreover, you have to add a launcher function like `run_XXXX()`. When you are done you need to write a test in **tests/test_myspikesorter.py**. In order to be tested, you can -install the required packages by changing the **.travis.yml**. Note that MATLAB based tests cannot be run at the moment, +install the required packages by changing the **pyproject.toml**. Note that MATLAB based tests cannot be run at the moment, but we recommend testing the implementation locally. -After this you need to add a block in doc/sorters_info.rst +After this you need to add a block in **doc/sorters_info.rst** Finally, make a pull request to the spikesorters repo, so we can review the code and merge it to the spikesorters! From 34673493da93e56902648a12ce57ca38afebfd0e Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Sat, 28 Oct 2023 01:01:51 +0000 Subject: [PATCH 2/6] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- doc/development/development.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/development/development.rst b/doc/development/development.rst index 71f3fb580d..30bf55dcab 100644 --- a/doc/development/development.rst +++ b/doc/development/development.rst @@ -202,10 +202,10 @@ This allows users to quickly understand the type of data that should be input in great_data: dict A dictionary of the processed data """ - -Note that in this example we demonstrate two other docstring conventions followed by SpikeInterface. First, that all string arguments should be presented -with double quotes. This is the same stylistic convention followed by Black and enforced by the pre-commit for the repo. Second, when a parameter is a + +Note that in this example we demonstrate two other docstring conventions followed by SpikeInterface. First, that all string arguments should be presented +with double quotes. This is the same stylistic convention followed by Black and enforced by the pre-commit for the repo. Second, when a parameter is a string with a limited number of values (e.g. :code:`mean` and :code:`median`), rather than give the type a value of :code:`str`, please list the possible strings so that the user knows what the options are. From a7004e418fce8ca4a6f19d0894c1bb7000164ae3 Mon Sep 17 00:00:00 2001 From: Zach McKenzie <92116279+zm711@users.noreply.github.com> Date: Sun, 29 Oct 2023 07:22:13 -0400 Subject: [PATCH 3/6] Add subsection headers --- doc/development/development.rst | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/doc/development/development.rst b/doc/development/development.rst index 30bf55dcab..9f84601c7a 100644 --- a/doc/development/development.rst +++ b/doc/development/development.rst @@ -120,9 +120,16 @@ The following steps are common to all operating systems: Stylistic conventions --------------------- +SpikeInterface maintains a consistent coding style across the project. This helps to ensure readability and +maintainability of the code, making it easier for contributors to collaborate. To facilitate code style +for the developer we use the follwing tools and conventions: -SpikeInterface maintains a consistent coding style across the project, leveraging the Black Python code formatter. -This helps to ensure readability and maintainability of the code, making it easier for contributors to collaborate. + +Install Black and pre-commit +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +We use the python formatter Black, with defaults set in the :code:`pyproject.toml`. This allows for +easy local formatting of code. To install Black, you can use pip, the Python package installer. Run the following command in your terminal: @@ -133,7 +140,7 @@ To install Black, you can use pip, the Python package installer. Run the followi This will install Black into your current Python environment. In addition to Black, we use pre-commit to manage a suite of code formatting. -Pre-commit helps to automate the process of running these tools before every commit, +Pre-commit helps to automate the process of running these tools (including Black) before every commit, ensuring that all code is checked for style. You can install pre-commit using pip as well: @@ -168,10 +175,13 @@ To ignore a block of code you must flank the code with two comments: code here # fmt: on -As described in the `black documentation `_, +As described in the `black documentation `_. -For docstrings, SpikeInterface generally follows `numpy docstring standard `_. +Docstring Conventions +^^^^^^^^^^^^^^^^^^^^^ + +For docstrings, SpikeInterface generally follows the `numpy docstring standard `_. This includes providing a one line summary of a function, and the standard NumPy sections including :code:`Parameters`, :code:`Returns`, etc. The format used for providing parameters, however is a little different. The project prefers the format: @@ -209,7 +219,9 @@ with double quotes. This is the same stylistic convention followed by Black and string with a limited number of values (e.g. :code:`mean` and :code:`median`), rather than give the type a value of :code:`str`, please list the possible strings so that the user knows what the options are. -The following are some additional styling conventions that we follow in SpikeInterface: + +Miscelleaneous Stylistic Conventions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #. Avoid using abreviations in variable names (e.g., use :code:`recording` instead of :code:`rec`). It is especially important to avoid single letter variables. #. Use index as singular and indices for plural following the NumPy convention. Avoid idx or indexes. Plus, id and ids are reserved for identifiers (i.e. channel_ids) From 666e90da10d173463e4ddcb640d3fb7d8aa756fd Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Sun, 29 Oct 2023 11:22:31 +0000 Subject: [PATCH 4/6] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- doc/development/development.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/development/development.rst b/doc/development/development.rst index 9f84601c7a..6f70aa7f4d 100644 --- a/doc/development/development.rst +++ b/doc/development/development.rst @@ -120,7 +120,7 @@ The following steps are common to all operating systems: Stylistic conventions --------------------- -SpikeInterface maintains a consistent coding style across the project. This helps to ensure readability and +SpikeInterface maintains a consistent coding style across the project. This helps to ensure readability and maintainability of the code, making it easier for contributors to collaborate. To facilitate code style for the developer we use the follwing tools and conventions: @@ -128,7 +128,7 @@ for the developer we use the follwing tools and conventions: Install Black and pre-commit ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -We use the python formatter Black, with defaults set in the :code:`pyproject.toml`. This allows for +We use the python formatter Black, with defaults set in the :code:`pyproject.toml`. This allows for easy local formatting of code. To install Black, you can use pip, the Python package installer. Run the following command in your terminal: From d74ee840f29173337d371986950ecbaeb0bbc4e6 Mon Sep 17 00:00:00 2001 From: Zach McKenzie <92116279+zm711@users.noreply.github.com> Date: Sun, 29 Oct 2023 08:10:36 -0400 Subject: [PATCH 5/6] update datalad instructions --- doc/development/development.rst | 43 +++------------------------------ 1 file changed, 4 insertions(+), 39 deletions(-) diff --git a/doc/development/development.rst b/doc/development/development.rst index 6f70aa7f4d..3df9afbdab 100644 --- a/doc/development/development.rst +++ b/doc/development/development.rst @@ -77,45 +77,10 @@ The extractor tests require datalad for some of the tests. Here are instructions Installing Datalad ------------------ -First install the datalad-installer package using pip: - -.. code-block:: shell - - pip install datalad-installer - -The following instructions depend on the operating system you are using: - -Linux -^^^^^ -.. code-block:: shell - - datalad-installer --sudo ok git-annex --method datalad/packages - -Mac OS -^^^^^^ -.. code-block:: shell - - datalad-installer --sudo ok git-annex --method brew - -Windows -^^^^^^^ - -.. code-block:: shell - - datalad-installer --sudo ok git-annex --method datalad/git-annex:release - - -The following steps are common to all operating systems: - -.. code-block:: shell - - pip install datalad - -(Optional) Configure Git to use git-annex for large files for efficiency: - -.. code-block:: shell - - git config --global filter.annex.process "git-annex filter-process" +In order to get datalad for your OS please see the `datalad instruction `_. +For more information on datalad visit the `datalad handbook `_. +Note, this will also require having git-annex. The instruction links above provide information on also +downloading git-annex for your particular OS. Stylistic conventions --------------------- From 7ca0fb7e58e3a2d813622e44402d30e724ef4e6e Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Sun, 29 Oct 2023 12:10:54 +0000 Subject: [PATCH 6/6] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- doc/development/development.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/development/development.rst b/doc/development/development.rst index 3df9afbdab..dc10b0c470 100644 --- a/doc/development/development.rst +++ b/doc/development/development.rst @@ -78,9 +78,9 @@ Installing Datalad ------------------ In order to get datalad for your OS please see the `datalad instruction `_. -For more information on datalad visit the `datalad handbook `_. +For more information on datalad visit the `datalad handbook `_. Note, this will also require having git-annex. The instruction links above provide information on also -downloading git-annex for your particular OS. +downloading git-annex for your particular OS. Stylistic conventions ---------------------