From a93d25b9e26b22be2620991b379fc3d9d03c2484 Mon Sep 17 00:00:00 2001 From: chrishalcrow Date: Wed, 22 May 2024 10:01:07 +0000 Subject: [PATCH] adding new project --- .../README.md | 34 +++++++++++++++++++ .../src/README.md | 1 + 2 files changed, 35 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..698ed1b --- /dev/null +++ b/projects/standardise_docstrings_to_numpydoc(?)_standard/README.md @@ -0,0 +1,34 @@ +# 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 + + + 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