Merge pull request #56 from ImperialCollegeLondon/basic-dev-docs

Add intro documentation for developers

CONTRIBUTING.md

@@ -6,50 +6,38 @@ If you have a suggestion, please open an issue describing in detail the change y
 
 If you would like to contribute code, please:
 
-1. Fork the repository
+1. Install PyProBE with [developer settings](https://congenial-adventure-mz797n5.pages.github.io/installation.html)
 
-2. Install the development requirements:
+2. Open an issue to detail the change/addition you wish to make, unless one already exists
 
-```bash
-$ source .venv/bin/activate
-$ pip install -r requirements-dev.txt
-```
+3. Create a feature branch and make your changes
 
-3. Install the git pre-commit hooks:
-
-```bash
-$ pre-commit install
-```
-
-4. Open an issue to detail the change/addition you wish to make, unless one already exists
-
-5. Create a feature branch and make your changes
-
-6. Follow [Google's docstring style](https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings) and ensure that the [documentation builds](#viewing-the-api-documentation) successfully:
+4. Follow [Google's docstring style](https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings) and ensure that the [documentation builds](#viewing-the-api-documentation) successfully:
 
 ```bash
 $ cd docs
 $ make html
 ```
 
-7. Ensure that all tests pass:
+5. Ensure that all tests pass:
 
 ```bash
 $ pytest
 ```
 
-8. Open a pull request. In the pull request description, please describe in detail the changes your feature branch introduces, and reference the associated issue.
+6. Open a pull request. In the pull request description, please describe in detail the changes your feature branch introduces, and reference the associated issue.
 
-## Packages and dependencies
-You are welcome to suggest and add new dependencies, if required for your functionality. There are two limits to this:
+## PyProBE structure
+Additions to the code should be made in accordance with the structure of PyProBE, to 
+maximise compatibility and ensure it is a maintainable package. Guidance for writing
+code for PyProBE includes:
 1. DataFrame operations should only be done using polars expressions. Data should be kept by default in polars LazyFrame format and only converted to DataFrame if needed for a particular operation.
-2. Input variables to methods should be 1-Dimensional numpy arrays.
+2. Method classes should be written in the format described in the [documentation](
+    https://congenial-adventure-mz797n5.pages.github.io/creating_a_new_method.html
+).
 
 ## Viewing the API documentation
 
 API documentation is built in html format, and stored locally in docs/build/html/. This can be viewed in your browser at docs/build/html/index.html.
 
-The documentation is also continuously deployed via GitHub Actions, and can be viewed [here](https://congenial-adventure-mz797n5.pages.github.io).
-
-## Viewing benchmark performance
-The results run on every push to the main branch can be viewed [here](https://congenial-adventure-mz797n5.pages.github.io/dev/bench/index.html)
+The documentation is also continuously deployed via GitHub Actions, and can be viewed [here](https://congenial-adventure-mz797n5.pages.github.io).

docs/source/creating_a_new_method.rst

@@ -1,4 +1,71 @@
 .. _creating_a_new_method:
 
 Creating a New Method
-=====================
+=====================
+In PyProBE :class:`Methods <pyprobe.methods.basemethod.BaseMethod>` are classes that 
+perform further analysis of the data. They can be peformed on any 
+:class:`~pyprobe.rawdata.RawData` or :class:`~pyprobe.result.Result` object.
+
+This document describes the standard format to be used for all PyProBE methods. 
+Constructing your method in this way ensures compatibility with the rest of the 
+PyProBE package, while keeping your code clean and easy to read.
+
+Start by creating your class, and an __init__ method. This is where all of the 
+variable assignement is performed:
+1. Define the input variables to the method using the 
+   :meth:`~pyprobe.methods.basemethod.BaseMethod.variable` method.
+2. Perform the calculations using the input variables and any other functions defined
+   inside this method class.
+3. Assign the results to the class attributes, which allows them to be read as 
+   :class:`~pyprobe.result.Result` objects.
+
+Then you can add any additional functions to perform your calculations. Keep these
+simple, defining all inputs as numpy arrays with minimal dimensionality. For instance,
+in the example below, current and time are both 1D numpy arrays. The code could have
+performed the same calculations using a single 2D array with a column for each variable,
+however this would have made the code less readable.
+
+.. code-block:: python
+
+    from pyprobe.methods.basemethod import BaseMethod
+
+    class CoulombCounter(BaseMethod):
+      """"A method for calculating the charge passed.""""
+
+        def __init__(self, input_data: Result):
+            """Initialise the coulomb counter method.
+            
+            Args:
+                data: The input data to the method.
+            """
+            # define input variables to the method
+            self.current = self.variable("Current [A]")
+            self.time = self.variable("Time [s]")
+
+            # perform the calculations
+            self.charge = self.coulomb_count(self.current, self.time)
+
+            # assign the results, by calling the assign_outputs method on a dictionary
+            # of the results of your method
+            self.result = self.assign_outputs({"Charge [C]": self.charge})
+        
+        def coulomb_count(self, current, time):
+            """Calculate the charge passed.
+            
+            Args:
+                current: The current data.
+                time: The time data.
+            
+            Returns:
+                The charge passed.
+            """
+            return np.trapz(current, time)
+
+The result of the method above can be accessed as a result object by calling:
+
+.. code-block:: python
+
+    result = CoulombCounter(data).result
+
+Which can be passed to any other Method or used in the :class:`~pyprobe.plot.Plot` 
+class.

docs/source/developer_guide.rst

@@ -4,5 +4,5 @@ Developer Guide
 .. toctree::
    :maxdepth: 2
 
-   installation
+   developer_installation
    creating_a_new_method

docs/source/developer_installation.rst

@@ -0,0 +1,65 @@
+Installation
+============
+
+To install PyProBE you must be running Python 3.11 or later. It is recommended to use a 
+virtual environment to install PyProBE, for example venv or conda.
+
+The steps to install PyProBE wih developer settings are as follows:
+
+1. Enter a directory in which you wish to install PyProBE:
+
+   .. code-block:: bash
+
+      cd /path/to/your/directory
+
+2. Clone the repository to your local machine. This can be done either from the 
+   main PyProBE repository or your own fork. This creates a directory called PyProBE.
+
+   .. code-block:: bash
+
+      git clone https://github.com/ImperialCollegeLondon/PyProBE.git
+      cd PyProBE
+
+3. Create and activate a virtual environment.
+
+  .. tabs::
+      .. tab:: venv
+
+         In your working directory:
+
+         .. code-block:: bash
+
+            python -m venv venv
+            source .venv/bin/activate
+
+      .. tab:: conda
+
+         In any directory:
+
+         .. code-block:: bash
+
+            conda create -n pyprobe python=3.12
+            conda activate pyprobe
+
+3. Install PyProBE as a package into your virtual environment:
+
+   .. code-block:: bash
+
+      cd /path/to/your/directory/PyProBE
+      pip install -e .
+
+   The :code:`-e` flag installs in "editable" mode, which means changes that you 
+   make to the code will be automatically reflected in the package inside your
+   virtual environment.
+
+4. Install the developer dependencies:
+
+   .. code-block:: bash
+
+      pip install -r requirements-dev.txt
+
+5. Install the pre-commit hooks:
+
+   .. code-block:: bash
+
+      pre-commit install