You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Updating infrastructure. Decided on docstring format (numpy) and experimenting with type hinting (mypy checked). Switching to pyproject.toml instead of setup.py
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+54-1Lines changed: 54 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -42,7 +42,7 @@ When making changes, we try to follow the procedure below.
42
42
**TODO: Once there is a "user" way to install, move the git clone etc. information here [#105](https://github.com/CardiacModelling/pcpostprocess/issues/105).**
43
43
44
44
```
45
-
pip install -e .[test]
45
+
pip install -e .[dev]
46
46
```
47
47
48
48
## Style guidelines
@@ -62,6 +62,17 @@ In addition to the rules checked by flake8, we try to use single quotes (`'`) fo
62
62
63
63
Class, method, and argument names are in UK english.
64
64
65
+
### Type hints
66
+
67
+
We'll try to use [type hints](https://docs.python.org/3/library/typing.html), checked with [mypy](https://www.mypy-lang.org/).
68
+
69
+
To run locally, use
70
+
```
71
+
$ mypy
72
+
```
73
+
74
+
Mypy is configured in `pyproject.toml`.
75
+
65
76
## Documentation
66
77
67
78
Every method and every class should have a [docstring](https://www.python.org/dev/peps/pep-0257/) that describes in plain terms what it does, and what the expected input and output is.
@@ -70,6 +81,48 @@ The only exception are unit test methods starting with `test_` - unit test class
70
81
Each docstring should start with a one-line explanation.
71
82
If more explanation is needed, this one-liner is followed by a blank line and more information in the following paragraphs.
72
83
84
+
Pcpostprocess uses the [Numpy docstring syntax](https://numpydoc.readthedocs.io/en/latest/format.html) for parameters and return values.
85
+
For example:
86
+
87
+
```
88
+
Single line explanation.
89
+
90
+
Detailed, multi-line explanation.
91
+
Possibly with ``code`` examples or even latex :math:`\sqrt{x}`.
92
+
93
+
Parameters
94
+
----------
95
+
x : int
96
+
Description of parameter ``x``.
97
+
y : float, default=1
98
+
Description of the optional parameter ``y``. If not set, the default value
99
+
1 will be used
100
+
z : str, optional
101
+
Description of the optional parameter ``z``. If not given, ``z`` won't be
102
+
used.
103
+
104
+
Returns
105
+
-------
106
+
float
107
+
Description of the returnved value
108
+
```
109
+
110
+
Return values can also be named, which is especially useful when there are multiple
111
+
112
+
```
113
+
Returns
114
+
-------
115
+
g: float
116
+
The estimated conductance, in nS.
117
+
E : float
118
+
The estimated reversal potential, in mV.
119
+
```
120
+
121
+
(Note that the numpy documentation currently suggests using single backticks ``` `x` ``` when describing parameters, but Sphinx doesn't fully support this yet.
122
+
Until this is fully supported, we will use double backticks as in the example above).
-`staircaseramp (2)_2kHz_15.17.19`, staircase run as final protocol
99
-
100
-
Here each directory name is a protocol name followed by a timestamp.
101
-
Corresponding dictionaries could be `Q2S_DC = {'staircaseramp (2)_2kHz': 'staircase'}` (indicating the staircase protocol) and `D2S = {'StaircaseInStaircaseramp (2)_2kHz': 'sis'}`.
102
-
The saveID could be any string, but in our example we use `saveID = '13112023_MW2'`
0 commit comments