Skip to content

Commit

Permalink
Merge pull request #2138 from zm711/dev-docs
Browse files Browse the repository at this point in the history 
Add `Docstring` section to development docs
  • Loading branch information
@alejoe91
alejoe91 authored Oct 31, 2023
2 parents 6df7c0f + 7ca0fb7 commit fabccac
Showing 1 changed file with 79 additions and 55 deletions.
134 changes: 79 additions & 55 deletions doc/development/development.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -77,97 +77,121 @@ The extractor tests require datalad for some of the tests. Here are instructions
Installing Datalad
------------------

First install the datalad-installer package using pip:
In order to get datalad for your OS please see the `datalad instruction <https://www.datalad.org>`_.
For more information on datalad visit the `datalad handbook <https://handbook.datalad.org/en/latest/>`_.
Note, this will also require having git-annex. The instruction links above provide information on also
downloading git-annex for your particular OS.

.. code-block:: shell
Stylistic conventions
---------------------

pip install datalad-installer
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:

The following instructions depend on the operating system you are using:

Linux
^^^^^
.. code-block:: shell
Install Black and pre-commit
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

datalad-installer --sudo ok git-annex --method datalad/packages
We use the python formatter Black, with defaults set in the :code:`pyproject.toml`. This allows for
easy local formatting of code.

Mac OS
^^^^^^
.. code-block:: shell
To install Black, you can use pip, the Python package installer. Run the following command in your terminal:

datalad-installer --sudo ok git-annex --method brew
.. code-block:: bash
Windows
^^^^^^^
pip install black
.. code-block:: shell
This will install Black into your current Python environment.

datalad-installer --sudo ok git-annex --method datalad/git-annex:release
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 (including Black) before every commit,
ensuring that all code is checked for style.

You can install pre-commit using pip as well:

The following steps are common to all operating systems:
.. code-block:: bash
.. code-block:: shell
pip install pre-commit
pip install datalad
(Optional) Configure Git to use git-annex for large files for efficiency:
Once pre-commit is installed, you can set up the pre-commit hooks for your local repository.
These hooks are scripts that pre-commit will run prior to each commit. To install the pre-commit hooks,
navigate to your local repository in your terminal and run the following command:

.. code-block:: shell
.. code-block:: bash
git config --global filter.annex.process "git-annex filter-process"
pre-commit install
Stylistic conventions
---------------------
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:

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.
.. code-block:: python
To install black, you can use pip, the Python package installer. Run the following command in your terminal:
# fmt: skip
.. code-block:: bash
To ignore a block of code you must flank the code with two comments:

pip install black
.. code-block:: python
This will install black into your current Python environment.
# fmt: off
code here
# fmt: on
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.
As described in the `black documentation <https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#code-style>`_.

You can install pre-commit using pip as well:

Docstring Conventions
^^^^^^^^^^^^^^^^^^^^^

For docstrings, SpikeInterface generally follows the `numpy docstring standard <https://numpydoc.readthedocs.io/en/latest/format.html#numpydoc-docstring-guide>`_.
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
pip install pre-commit
parameter_name: type, default: default_value
Once pre-commit is installed, you can set up the pre-commit hooks for your local repository.
These hooks are scripts that pre-commit will run prior to each commit. To install the pre-commit hooks,
navigate to your local repository in your terminal and run the following command:
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:: bash
.. code-block:: python
pre-commit install
def a_function(param_a, param_b=5, param_c="mean"):
"""
A function for analyzing data
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.
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
If you want black to omit a line from formatting, you can add the following comment to the end of the line:
Returns
-------
great_data: dict
A dictionary of the processed data
"""
.. code-block:: python
# fmt: off
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.

As described in the `black documentation <https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#code-style>`_,

The following are some 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 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 <https://numpydoc.readthedocs.io/en/latest/format.html#numpydoc-docstring-guide>`_ in all the docstrings.


How to build the documentation
------------------------------
Expand Down Expand Up @@ -199,14 +223,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 <https://github.com/NeuralEnsemble/python-neo>`_
supported formats list (***ref***). Most of the extractors rely on the `NEO <https://github.com/NeuralEnsemble/python-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 <https://github.com/NeuralEnsemble/python-neo/blob/master/neo/rawio/examplerawio.py#L44>`_).
Therefore, to implement a new extractor to handle the unsupported format, we recommend making a new :code:`neo.rawio.BaseRawIO` class (see `example <https://github.com/NeuralEnsemble/python-neo/blob/master/neo/rawio/examplerawio.py#L44>`_).
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 <https://github.com/SpikeInterface/spikeinterface/blob/0.96.1/spikeinterface/extractors/neoextractors/spikeglx.py>`_
or `Neuralynx <https://github.com/SpikeInterface/spikeinterface/blob/0.96.1/spikeinterface/extractors/neoextractors/neuralynx.py>`_).

Expand Down Expand Up @@ -345,9 +369,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!

0 comments on commit fabccac

Please sign in to comment.