Improve documentation layout and clarity of text

docs/conventions.md

@@ -0,0 +1,42 @@
+# Conventions
+
+## Units
+
+We use SI units for the model parameters, except for angles (we use degrees instead of radians) and target strength (we use deciBels).  All model code must accept inputs and produce results using the units below. If the model calculations use different units internally, the code should internally convert between the them.
+
+| Parameter | Units | Notes |
+|-----------|-------|--|
+|length, diameter, radius, thickness, etc|m||
+|density|kg/m³||
+|sound speed|m/s||
+|angle|°|See [Coordinate systems][coordinate-systems]|
+|frequency|Hz||
+|target strength|dB|reference value is 1 m²|
+
+## Coordinate systems
+
+A single coordinate system should be used for all models provided by echoSMs. The aim is to ease the comparison of results between different models.
+
+The right-handed spherical coordinate system as defined by ISO 80000-2[^1] is to be used, as illustrated below. The organism should lie along the _z_-axis with the positive _x_-axis extending above the dorsal surface of the organism:
+
+<!--- This code will include an html file, originally used to
+include a live 3D view of the coordinate system, but there are
+issues with the html so for the moment a 2D image is used.
+<p align="center">
+<iframe src="../coordinate_system2.html" title="Coordinate system" width="100%" height="500" frameborder="0"></iframe>
+</p>
+--->
+
+![The coordinate system](resources/coordinate_system.svg){:style="height:400px;width400px"}
+
+The definitions are such that for _ɸ_=0°, _θ_ values of 0°, 90°, and 180° correspond to acoustic wave incidence angles of head on, dorsal, and tail on, respectively. Note that the definition of these angles is in terms of the acoustic wave, not the orientation of the organism (which should always be as shown in the illustration).
+
+All model code should accept angles and produce results in this coordinate system. If the model calculations use a different coordinate system, the code should internally convert between the system given above and the version used in the code.
+
+## Code style
+
+Contributions of code should follow standardised or community-agreed styles and be provided in (or added to) a structure suitable for packaging and uploading to package libraries. For Python this includes `pip` and/or `conda`, for R this would be `CRAN`, for Matlab this would be a toolbox on the MATLAB File Exchange, etc.
+
+Python code should follow [PEP8](https://peps.python.org/pep-0008) and docstrings should use [PEP257](https://peps.python.org/pep-0257/) with the contents following the [numpydoc style](https://numpydoc.readthedocs.io/en/latest/format.html). An exception to PEP8 is made to allow lines of up to 100 characters.
+
+[^1]: [ISO. 2019.](https://www.iso.org/obp/ui/en/#iso:std:iso:80000:-2:ed-2:v2:en) ISO 80000-2. Part 2: Mathematics.

docs/index.md

@@ -10,6 +10,12 @@ Quantitative interpretation of acoustic echograms requires software expertise to
 
 The goal of this project is to make acoustic scattering models available to fisheries and plankton acoustic scientists via the world wide web. By providing the models in an open-access and open-source software language (e.g, Python, R) and providing morphological and anatomical data in open data formats (e.g., HDF5, relational databases), the proper and appropriate use of these models can extend to the entire fisheries and plankton acoustics’ community.
 
+## Contributing to echoSMs
+
+We welcome all contributions to echoSMs, be it code, test cases, bug reports, discussion of models, etc. Please use the [github](https://github.com/ices-tools-dev/echoSMs) facilities for this (i.e., [issues](https://github.com/ices-tools-dev/echoSMs/issues), [pull requests](https://github.com/ices-tools-dev/echoSMs/pulls), and [discussions](https://github.com/ices-tools-dev/echoSMs/discussions)). We are also happy to accept directly code that we can add to echoSMs on your behalf.
+
+An objective of echoSMs is to provide scattering models in a form that is easy to access, use, and compare to other models. To help with that, we [specify][conventions] model parameter units, angle conventions, and required model outputs that code contributions should support. We also suggest coding conventions that should be followed.
+
 ## Scattering Models
 
 The initial set of acoustic scattering models will be those used in [Jech et al. (2015)](https://doi.org/10.1121/1.4937607). Acoustic model development will follow 3–4 phases:

mkdocs.yml

@@ -2,7 +2,7 @@ site_name: echoSMs
 nav:
     - Introduction: index.md
     - Usage: usage.md
-    - Contributing: contributing.md
+    - Conventions: conventions.md
     - Benchmarks: benchmark_data.md
     - API reference: api_reference.md
     - Other software: other_software.md

src/echosms/ptdwbamodel.py

@@ -27,7 +27,7 @@ def calculate_ts_single(self, volume, theta, phi, f, voxel_size, rho, c, **kwarg
         Warning
         -------
         Input parameters `theta`, `phi`, and the orientation of `volume` do not currently follow the
-        echoSMs [coordinate system](contributing.md#coordinate-systems).
+        echoSMs [coordinate system](conventions.md#coordinate-systems).
 
         Parameters
         ----------