Add contributing guide (#185)

* Remove TODO comment.

* First dev docs version.

* Add contributing guide.

* Adjust slightly the feature roadmap attention.

* Ensure ordering of get started page is fixed.

docs/source/community/contributing_guidelines.md

@@ -0,0 +1,143 @@
+# Contributing Guide
+
+**Contributions to `spikewrap`` are very welcome and appreciated. This could be
+fixing a bug, improving the documentation or developing a new feature.
+
+If you're unsure about any part of the contributing process or have any questions, please
+get in touch through our [Zulip chat](https://neuroinformatics.zulipchat.com/#narrow/stream/406002-Spikewrap).
+Otherwise, feel free to dive right in and start contributing by
+[creating a development environment](#creating-a-development-environment)
+and [opening a pull request](#pull-requests).
+
+## Creating a development environment
+
+To install ``spikewrap`` for development, first the
+[GitHub repository](https://github.com/neuroinformatics-unit/spikewrap)
+should be cloned. Then, you can change-directory
+to the cloned repository and run pip install with the developer tag:
+
+```sh
+pip install -e .[dev]
+```
+
+or if using `zsh`:
+
+```sh
+pip install -e '.[dev]'
+```
+
+Finally, initialise the [pre-commit hooks](#formatting-and-pre-commit-hooks):
+
+```bash
+pre-commit install
+```
+
+
+## Pull requests
+
+In all cases, please submit code to the main repository via a pull request. The developers recommend and adhere
+to the following conventions:
+
+- Please submit *draft* pull requests as early as possible (you can still push to the branch once submitted) to
+  allow for discussion.
+- One approval of a PR (by a repo maintainer) is sufficient for it to be merged.
+- If the PR receives approval without additional comments, it will be merged immediately by the approving reviewer.
+
+A typical PR workflow would be as follows:
+* Create a new branch, make your changes, and add them with `git add`.
+* When you attempt to commit, the [pre-commit hooks](#formatting-and-pre-commit-hooks) will be triggered.
+* `git add` any changes made by the hooks, and commit. More information on dealing with the [pre-commit hooks](#formatting-and-pre-commit-hooks) is available below.
+* Push your changes to GitHub and open a draft pull request.
+* Please don't hesitate to ask any developer for help on draft pull requests at our [Zulip chat](https://neuroinformatics.zulipchat.com/#narrow/stream/406002-Spikewrap).
+* If all checks run successfully, mark the pull request as ready for review.
+* Respond to review comments and implement any requested changes.
+* One of the maintainers will approve the PR.
+* Your PR will be merged into the *main* branch!
+
+## Formatting and pre-commit hooks
+
+Running `pre-commit install` will set up [pre-commit hooks](https://pre-commit.com/) to ensure a consistent formatting style. Currently, these include:
+* [ruff](https://github.com/astral-sh/ruff), which does a number of jobs including code linting and auto-formatting.
+* [mypy](https://mypy.readthedocs.io/en/stable/index.html), a static type checker.
+* [black](https://github.com/psf/black), an auto-formatter.
+* [check-manifest](https://github.com/mgedmin/check-manifest), to ensure that the right files are included in the pip package.
+* [codespell](https://github.com/codespell-project/codespell), to check for common misspellings.
+
+
+Pre-commit hooks will automatically run when a commit is made.
+To manually run all the hooks before committing:
+
+```sh
+pre-commit run     # for staged files
+pre-commit run -a  # for all files in the repository
+```
+
+Some problems will be automatically fixed by the hooks. In this case, you should
+stage the auto-fixed changes and run the hooks again:
+
+```sh
+git add .
+pre-commit run
+```
+
+If a problem cannot be auto-fixed, the corresponding tool will provide
+information on what the issue is and how to fix it. For example, `ruff` might
+output something like:
+
+```sh
+session.py:551:80: E501 Line too long (90 > 79)
+```
+
+This pinpoints the problem to a single line of code and a specific [ruff rule](https://docs.astral.sh/ruff/rules/) violation.
+Sometimes you may have good reasons to ignore a particular rule for a specific line.
+You can do this by adding an inline comment, e.g. `# noqa: E501`. Replace `E501` with the code of the rule you want to ignore.
+
+Don't worry if you are stuck and are not sure how to fix linting
+issues. Feel free to commit with the `--no-verify` option which will
+skip pre-commit checks, and ask for help in your PR.
+
+For docstrings, we adhere to the [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html) style.
+Make sure to provide docstrings for all public functions, classes, and methods.
+
+## Contributing documentation
+
+If you notice any areas where the documentation can be improved, 
+please don't hesitate to make a contribution.
+
+### Working with the documentation
+
+The documentation is found in the `docs/source` folder, where the structure mirrors the rendered website.
+
+Dependencies for building the documentation locally can be found at `docs/requirements.txt`.
+To install these, change directory to the `docs` folder in your terminal and type:
+
+```
+pip install -r requirements.txt
+```
+
+The command to build the documentation is:
+
+```
+make clean html
+```
+
+Any existing builds will be removed, and documentation will be built and output 
+to the `build` folder. To read the built documentation in a browser, navigate to the `build`
+folder and open the `index.html` file.
+
+
+### Editing the documentation
+
+The documentation is hosted using [GitHub Pages](https://pages.github.com/), and the source can be found at
+[GitHub](https://github.com/neuroinformatics-unit/spikewrap/tree/main/docs).
+Most content is found under `docs/source`, where the structure mirrors the rendered website.
+
+To edit a page, please:
+
+- Fork the repository
+- Make edits to the relevant pages
+- Build the pages as above to inspect your changes
+- Create a pull request outlining the changes made
+
+If you aren't sure where the changes should be made, please
+[get in touch!](https://neuroinformatics.zulipchat.com/#narrow/stream/406002-Spikewrap)

docs/source/community/feature_roadmap.md

@@ -3,9 +3,8 @@
 
 :::{attention}
 
-Currently, the interface of ``spikewrap`` is under review. Most features described
-are available under a [development branch](https://github.com/neuroinformatics-unit/spikewrap/tree/dev),
-and will be quickly ported over to the main package when the interface is agreed.
+Currently, the interface of ``spikewrap`` is under review. The features described
+below will be added with high priority once the review is complete.
 
 ::::
 

docs/source/community/index.md

@@ -3,6 +3,13 @@
 
 We are very keen to get feedback on ``spikewrap``. Does this interface for running electrophysiology analysis will work for you?
 
+
+
+WE WANT FEEDBACK! X_)X)X)X)X)X)X)X)
+
+
+
+
 Please get in contact with feedback and suggestions, either by joining our 
 [Zulip Chat](https://neuroinformatics.zulipchat.com/#narrow/channel/406002-Spikewrap)
 or opening a
@@ -16,5 +23,7 @@ see our [Roadmap](roadmap) for details.
 :maxdepth: 2
 :hidden:
 
+contributing_guidelines
 feature_roadmap
+
 ```

docs/source/get_started/index.md

@@ -5,8 +5,8 @@
 :gutter: 4
 
 
-:::{grid-item-card} {fas}`download;sd-text-primary` Install
-:link: install
+:::{grid-item-card} {fas}`download;sd-text-primary` Installation
+:link: installation
 :link-type: doc
 :class-card: gallery-card
 
@@ -44,9 +44,9 @@ How ``spikewrap`` outputs processed data.
 :maxdepth: 2
 :hidden:
 
-install
+installation
+../gallery_builds/get_started/feature_overview
 supported_formats
 output_folder_formats
-../gallery_builds/get_started/feature_overview
 ```
 

docs/source/get_started/install.md → docs/source/get_started/installation.md

@@ -1,5 +1,5 @@
 (how-to-install)=
-# How to Install
+# Installation
 
 The simplest way to install spikewrap is with `pip`, a package manager that is 
 automatically included with Python.

docs/source/get_started/output_folder_formats.md

@@ -1,4 +1,4 @@
-# Output Folder Format
+# Output Folder Structure
 
 :::{attention}
 This output format is not set in stone. Please get in contact 

spikewrap/structure/session.py

@@ -77,7 +77,7 @@ def __init__(
         # expose a setter) for both internal and external calls.
         self._passed_run_names = run_names
         self._file_format = file_format
-        self._probe = probe  # TODO - this is the same object on all classes right?
+        self._probe = probe
 
         self._parent_input_path = parent_input_path
         self._ses_name = session_name