From 06f8406332e6eff46d1035ef1978f0910b822b55 Mon Sep 17 00:00:00 2001 From: chrishalcrow Date: Wed, 22 May 2024 09:34:47 +0000 Subject: [PATCH] adding new project --- .../README.md | 44 +++++++++++++++++++ .../src/README.md | 1 + 2 files changed, 45 insertions(+) create mode 100644 projects/standardise_docstrings_to_numpydoc(?)_standard/README.md create mode 100644 projects/standardise_docstrings_to_numpydoc(?)_standard/src/README.md diff --git a/projects/standardise_docstrings_to_numpydoc(?)_standard/README.md b/projects/standardise_docstrings_to_numpydoc(?)_standard/README.md new file mode 100644 index 0000000..4b36264 --- /dev/null +++ b/projects/standardise_docstrings_to_numpydoc(?)_standard/README.md @@ -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. + + diff --git a/projects/standardise_docstrings_to_numpydoc(?)_standard/src/README.md b/projects/standardise_docstrings_to_numpydoc(?)_standard/src/README.md new file mode 100644 index 0000000..80ea5e8 --- /dev/null +++ b/projects/standardise_docstrings_to_numpydoc(?)_standard/src/README.md @@ -0,0 +1 @@ +Add your code here