docs: updating design and contributors guide

Author: lachlangrose

docs/source/getting_started/contributors_guide.rst

@@ -50,13 +50,48 @@ For changes to ``./docs``::
 Building the docs the first time takes a little while. After this, you will see a build directory. From here you can preview the generated HTML 
 in your browser. 
 
+Linting and code format
+~~~~~~~~~~~~~~~~~~~~~~~
+
+We use both black and ruff to format and lint the code. 
+The code will automatically be formatted by black after being committed, alternatively run black on any changed files.
+
+A linting check is done with ruff, please ensure that this passes prior to creating a pull request.
+To check the code with ruff run the following command in the root directory of the repository::
+
+    ruff LoopStructural
+
+The configuration parameters for ruff and black are stored in the pyproject.toml file.
+
+Coding Guidelines
+~~~~~~~~~~~~~~~~~
+-	Reduce Duplicated Code: Strive to avoid duplication by modularizing code and promoting code reuse where appropriate.
+-	Document code: Use numpy style docstrings and ensure that any new features are added into the documentation
+-	Type hints: Use appropriate type hints for any function arguments and returns
+-	Avoid python loops: Avoid using pure python loops - where possible used vectorized functions in numpy, geopandas, scipy  
+-	Use Object-Oriented Data Structures: Utilize object-oriented programming principles to structure data and functionality in a cohesive manner.
+-	Use British English Spelling: Adhere to British English spelling conventions throughout the codebase and documentation.
+-	Use Conventional Commits: Follow the Conventional Commits specification for clear and structured commit messages.
+-	Ensure Tests Pass: Before submitting any changes, ensure that all tests pass locally.
+-	Write Tests for New Code: Include tests for any new functionality or code additions to maintain code quality and prevent regressions.
+-	Minimize External Dependencies: Aim to minimize reliance on external libraries and frameworks to keep the project lightweight.
+-	Make External Dependencies Optional: When external dependencies are necessary, make them optional where feasible to increase flexibility and ease of installation.
+
 Commit messages
 ---------------
 A changelog is automatically generated from the commit message, the following keywords are identified in the commit log.
 
- * add - defining a new feature that is added to LoopStructural
- * fix - a bugfix
- * change - any changes to features 
+.. code-block::
+    <type>[optional scope]: <description>
+
+    [optional body]
+
+    [optional footer(s)]
+
+
+ * feat: - defining a new feature that is added to LoopStructural
+ * fix: - a bugfix
+ * BREAKING CHANGE: - any changes to features 
  * remove - removing features or code from LoopStructural
  * merge 
  * doc - changes to documentation

docs/source/getting_started/loopstructural_design.rst

@@ -49,13 +49,19 @@ The main modules for the library are:
 2. modelling 
 3. visualisation
 4. utils
+5. datasets
+
+
 
 **Coding paradigm** LoopStructural is written in an object oriented paradigm.
 The four pillars of object oriented coding should be adhered to:
 
 * **Encapsulation**: Attributes in python are designed to be accessible both within the class and from outside of the class. In LoopStructural, the where an attribute of a class should be private the ``@property`` decorator should be used.
 * **Inheritance**: Classes should inheret attributes and methods from parent classes. 
 * **Polymorphism**: Child classes, where a method is different from a parent class should override methods from parent classes.
+* **Abstraction**: Classes should be designed to be abstract and avoid containing implementation details.
+
+**ABC** LoopStructural uses abstract base classes to define the interface for different classes. 
 
 **Dependency management** The library is written in python and is dependent on numpy, scipy. Care should be taken to avoid incorporating of uncessary dependencies. For dependencies that are not part of the standard scientific python toolkit (numfocus projects) the dependencies should be optional and not be required. 
 
@@ -65,6 +71,8 @@ The four pillars of object oriented coding should be adhered to:
 There should be unit tests for all classes and methods.
 Integration tests should be included to test the interaction between classes.
 
+**Commits** Commits should be made using the conventional commit style.
+
 **CI/CD** The code is automatically versioned using release-please. 
 When creating a commit use the conventional commit style e.g. ``fix: bug fix``, ``feat: new feature``, ``chore: code change``.
 A new patch pull request will be created when a bug fix is applied and passes the tests. 
@@ -120,6 +128,7 @@ A visualisation module can be implemented by simply subclassing the **BaseModelP
 ---------
 
 The utils module is a container for utility functions that are used throughout the library.
+Where possible util functions should be stored in separate files that are imported in the `__init__.py` file.
 
 
 
@@ -138,6 +147,7 @@ A fixture is a function that can be called by a test for a range of predefined p
 For example a fixture to generate different discrete interpolators would be
 
 .. code-block::
+
     from LoopStructural.interpolators import FiniteDifferenceInterpolator as FDI, \
                                             PiecewiseLinearInterpolator as PLI
     from LoopStructural.interpolators import StructuredGrid, TetMesh
@@ -165,7 +175,7 @@ For example a fixture to generate different discrete interpolators would be
 
 This fixture can then be called by any test in the testing suite:
 
-.. code-block:
+.. code-block::
     
     from LoopStructural.interpolators import GeologicalInterpolator