Skip to content

Commit

Permalink
adding new project
Browse files Browse the repository at this point in the history
  • Loading branch information
chrishalcrow authored May 22, 2024
1 parent a57390d commit 06f8406
Show file tree
Hide file tree
Showing 2 changed files with 45 additions and 0 deletions.
44 changes: 44 additions & 0 deletions projects/standardise_docstrings_to_numpydoc(?)_standard/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# Project title:

### Key Investigators

* Chris Halcrow

## Project Description

Bring our docstrings up to numpydoc standard (for one module)

### Background

Docstrings are important. If they are formatted properly, they can be used by other packages to autogenerate stuff e.g. Sphinx uses them to build our docs API. Future GUIs would depend on them, and having (typed?) good ones can make development much easier. Our are pretty good, but it would be nice if they were met a specific standard. I propose to bring the docstrings up to the numpydoc(?) standard: https://numpydoc.readthedocs.io/en/latest/format.html

To see the fun that awaits try running e.g. (sorry to pick on one function: this was the first one I saw!). Think it’d be good to try and do a module and see how long it takes, and how annoying it is. Ruff (https://docs.astral.sh/ruff/) can do linting based on this standard, which makes it easier to develop.

### Objectives

Standardise one module, find out how long this takes and what are the time-heavy steps (if they exist).

### Approach and Plan

* [ ] Make a simple workflow which makes standardising docstrings easy (probably installing the vscode ruff extension is enough)
* [ ] Standarise the docstrings for one module

### Progress

* [ ] Decide on which standard to use
* [ ] Standardise one docstring
* [ ] Figure out how long it takes to standardise one docstring => estimate size of task
* [ ] Standardise all docstrings in one module

### Getting started

Here are some instructions for getting ruff working as a docstring linter in VSCode.

1. Install the _ruff_ extension.
2. Add the following to spikeinterface's :

3. Restart VScode. Open (the alphabetically first file). The docstring for should have a wiggly line under it.
4. pip install ruff
5. run e.g. . The output should roughly match what's happening in VSCode.


Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Add your code here

0 comments on commit 06f8406

Please sign in to comment.