Add contributing and update index

CONTRIBUTING.md

@@ -0,0 +1,64 @@
+# Contributing to `piglot`
+
+Thank you for considering contributing to `piglot`!
+We appreciate your interest in helping us improve our project.
+
+## How to Contribute
+
+To contribute to `piglot`, please follow these steps:
+
+1. Fork the repository and create a new branch for your contribution.
+2. Make your changes or additions to the codebase.
+3. Write tests to ensure the correctness of your changes.
+4. Run the existing tests to make sure they pass.
+5. If relevant, build a set of appropriate examples for the new features and add them to the documentation.
+6. Commit your changes and push them to your forked repository.
+7. Submit a pull request to the main repository.
+
+### Tests
+
+When contributing with new features, also write tests for them in the `test` directory.
+We use `pytest` for this task in our CI framework.
+While we currently don't have strict test coverage requirements, new features should be extensively tested.
+
+### Examples
+
+We strongly encourage contributors to also build minimal working examples (MWEs) for new features or solvers.
+These should be placed inside the `examples` directory, along with the required additional files.
+A description of the example should also be added to the `docs/source/examples` directory, showing the usage and results of your example.
+Don't forget to add a reference to the indices in `docs/source/examples/*.rst`.
+
+### Input file templates
+
+If your new features require modifications to the `.yaml` configuration specification, these changes should be included in the input file templates.
+These are hosted in the `examples/templates` directory, which are then loaded by the documentation in `docs/source/templates`.
+If you add new solvers or optimisers, please update both locations with your new template.
+
+## Code Style
+
+Please adhere to the following code style guidelines when contributing to `piglot`:
+
+- Use spaces for indentation. We are using 4 spaces.
+- Follow the naming conventions used in the existing codebase.
+- Write clear and concise comments to explain your code.
+- Write docstrings for every module, method and class. We use the `numpy` docstring style.
+
+We use `flake8` for linting the code.
+Please refer to our configuration (`.flake8` in the repo root) for additional details.
+Compliance with this is enforced in our CI procedure.
+
+## Reporting Issues
+
+If you encounter any issues or have suggestions for improvement, please open an issue on the [issue tracker](https://github.com/CM2S/piglot/issues).
+Provide as much detail as possible to help us understand and address the problem.
+
+## Papers using `piglot`
+
+If you use `piglot` in your work, we encourage you to add your contribution to the [list of papers](docs/source/papers.md) using `piglot`.
+Feel free to open a PR for adding an entry to that list!
+
+## License
+
+By contributing to `piglot`, you agree that your contributions will be licensed under the [MIT License](https://opensource.org/licenses/MIT).
+
+We look forward to your contributions! Thank you for your support.

README.md

@@ -26,7 +26,10 @@ The primary emphasis is on derivative-free optimisation, ensuring compatibility
 * **Optimisation algorithms:** Off the shelf, there are several optimisers included in the package. Among them, we highlight our fully-fledged Bayesian optimisation (based on [BoTorch](https://botorch.org/)) that supports optimising stochastic and composite objectives and is highly customisable. Additional methods can also be easily implemented within `piglot`.
 * **Visualisation tools:** You can use the built-in tool `piglot-plot` to visualise the results of the optimisation. There are native plotting utilities for the optimised responses, the parameter history, objective history and, for supported solvers, live plotting of the currently running case. Also, an animation of the optimisation process can be exported.
 
-Feel free to explore, contribute, and optimize with `piglot`!
+Feel free to explore, [contribute](CONTRIBUTING.md), and optimise with `piglot`!
+We recommend starting by reading the [Getting started](#getting-started) section, and then checking the latest [documentation](https://piglot.readthedocs.io) for additional details.
+You can use our [discussions](https://github.com/CM2S/piglot/discussions) page for help and our [issue tracker](https://github.com/CM2S/piglot/issues) for reporting problems and suggestions.
+If you use this tool in your work, we encourage to open a PR to add it to our [list of papers](docs/source/papers.md).
 
 
 # Getting started
@@ -39,7 +42,9 @@ There are two modes of operation available: running using the given `piglot` and
 We use YAML configuration files to specify the optimisation problem to solve.
 This is the simplest form of using `piglot` and is the recommended approach unless you have a strong motive to use Python scripts (described [here](#using-python-scripts)).
 A simple analytical curve fitting problem is included to showcase how to use configuration files.
-In this case, we fit a quadratic expression of the type $f(x) = a x^2$.
+
+To keep things simple, in this case, we fit a quadratic expression of the type $f(x) = a x^2$.
+Note that this curve is generally obtained from a physics-based solver when solving an inverse problem.
 As a reference, a numerically generated reference from the expression $f(x) = 2 x^2$ is used (provided in the `examples/sample_curve_fitting/reference_curve.txt` file).
 We want to find the value for $a$ that better fits our reference (it should be 2).
 The configuration file for this example is:

docs/source/index.rst

@@ -46,8 +46,10 @@ We highlight:
 - **Optimisation algorithms:** Off the shelf, there are several optimisers included in the package. Among them, we highlight our fully-fledged Bayesian optimisation (based on `BoTorch <https://botorch.org/>`_) that supports optimising stochastic and composite objectives and is highly customisable. Additional methods can also be easily implemented within :code:`piglot`.
 - **Visualisation tools:** You can use the builtin tool :code:`piglot-plot` to visualise the results of the optimisation. There are native plotting utilities for the optimised responses, the parameter history, objective history and, for supported solvers, live plotting of the currently running case. Also, an animation of the optimisation process can be exported.
 
-Feel free to explore, contribute, and optimize with :code:`piglot`!
-
+Feel free to explore, `contribute <CONTRIBUTING.md>`_, and optimise with :code:`piglot`!
+We recommend starting by reading the `Getting started <https://github.com/CM2S/piglot?tab=readme-ov-file#getting-started>`_ section, and then checking the latest `documentation <https://piglot.readthedocs.io>`_ for additional details.
+You can use our `discussions <https://github.com/CM2S/piglot/discussions>`_ page for help and our `issue tracker <https://github.com/CM2S/piglot/issues>`_ for reporting problems and suggestions.
+If you use this tool in your work, we encourage to open a PR to add it to our list of papers.
 
 Installation
 ------------
@@ -118,7 +120,8 @@ If you wish to install all optimisers at once, you can run :code:`pip install pi
 
 .. toctree::
    :maxdepth: 1
-   :caption: API
+   :caption: Reference
    :hidden:
 
-   Reference <_autosummary/piglot>
+   API <_autosummary/piglot>
+   Papers <papers.md>