Add readmes

CONTRIBUTING.md

@@ -0,0 +1,46 @@
+# How to contribute to PowSyBl OpenRAO
+
+Welcome to the OpenRAO developers and users community!  
+Here is all the information you need to know before making your first contribution.
+
+## Submitting your ideas
+If you are an OpenRAO user, and you found a bug, or you would like a new feature, or 
+if you are an active OpenRAO developer, and have ideas to improve the code, please let us know! 
+We'll be more than happy to fix all bugs and discuss all improvement ideas.
+- First, make sure that the bug/feature request/improvement idea has not been already reported under [Issues](https://github.com/powsybl/powsybl-open-rao/issues).
+- If not, [open a new one](https://github.com/powsybl/powsybl-open-rao/issues/new). Provide us with as many details as possible, 
+  so we can understand the issue and try to address it ASAP. 
+- Label[^1] your new issue as much as possible, this makes addressing it much more efficient.
+
+Your ideas may be discussed by the OpenRAO developers and the [PowSyBl Technical Steering Committee](https://www.powsybl.org/pages/overview/governance#technical-steering-committee) 
+in order to reach a consensus.
+
+## Development
+
+### Getting started
+The PowSyBl OpenRAO team is always pleased to welcome developers into the project.  
+The best way to get a quick start is to clone the project's main branch and try running the [functional tests](tests/README.md) 
+on your PC. If everything works, then you're good to make your first contribution to the code!
+
+### Code formatting
+OpenRAO uses a custom profile for JAVA code formatting.  
+You can download these rules for your IDE from this directory: [developer-resources](docs/_static/developer-resources).  
+
+### Pull Requests
+The `main` branch is protected by a set of rules, and Pull Requests from your branch are mandatory.  
+
+Here is a set of rules your pull request must follow:
+- your commits must be **signed-off**
+- the description of the PR should be well detailed: it must be self-explanatory and detailed enough for developers and 
+  users to understand **what** has changed, **why**, and **how**
+- if the PR addresses an open issue, the **issue should be linked** in the description
+- you can open a PR even if it's not ready to merge, but in that case you must set it as a **draft**
+- the PR must be **reviewed** by at least one other developer before it can be merged
+- you must add unit **tests** and/or [functional tests](tests/README.md) to your new features
+- the PR must pass a few **automatic checks** before it can be merged: build & unit tests, functional tests, sonar quality, sign-off check, doc build check
+- if the PR changes a part of the code that is [documented](https://powsybl.readthedocs.io/projects/openrao/en/latest), 
+  then [**documentation**](docs) must be updated before it can be merged
+- **label**[^1] the PR as much as possible, this makes addressing it much more efficient
+
+
+[^1]: See OpenRAO's list of labels for Issues & Pull Requests [here](https://github.com/powsybl/powsybl-open-rao/issues/labels)

README.md

@@ -29,11 +29,7 @@ In order to build **powsybl-open-rao**, you need the following environment avail
 
 ### Installing
 
-Before installing **powsybl-open-rao**, you need to install OR-Tools, a software suite for optimisation that is used by Open RAO.
-
-Please refer to [OR-tools website](https://developers.google.com/optimization/install/download) for installation instructions.
-
-Open RAO also needs a load flow implementation and a sensitivity analysis implementation at runtime, following the interfaces of **powsybl-core** which documentation is available in [PowSyBl website](https://www.powsybl.org/pages/documentation/). Note that for obvious reasons, included performances, reliability and transparency, Open RAO uses [Powsybl Open Load Flow](https://github.com/powsybl/powsybl-open-loadflow) by default, but you can prefer you own implementation.
+Open RAO needs a load flow implementation and a sensitivity analysis implementation at runtime, following the interfaces of **powsybl-core** which documentation is available in [PowSyBl website](https://www.powsybl.org/pages/documentation/). Note that for obvious reasons, included performances, reliability and transparency, Open RAO uses [Powsybl Open Load Flow](https://github.com/powsybl/powsybl-open-loadflow) by default, but you can prefer you own implementation.
 
 ### Running
 
@@ -65,7 +61,13 @@ cd <install-prefix>/bin
 
 For more information about *itools*, do not hesitate to visit [PowSyBl documentation](https://www.powsybl.org/docs/).
 
+### Quick tutorial
+If you prefer to get familiar with OpenRAO using a real example, take a look at this [tutorial](https://powsybl.readthedocs.io/projects/openrao/en/stable/tutorial.html).
+
 ## License
 
 This project is licensed under the Mozilla Public License 2.0 - see the [LICENSE.txt](https://github.com/powsybl/powsybl-open-rao/blob/main/LICENSE.txt) file for details.
 
+## Contributing
+
+Please read the instructions [here](CONTRIBUTING.md).

docs/README.md

@@ -2,20 +2,48 @@
 
 These are the documentation sources for OpenRAO.  
 Please keep them up-to-date with your developments.  
-They are published on https://powsybl.readthedocs.org/projects/openrao and pull requests are built and previewed automatically.  
+They are published on https://powsybl.readthedocs.org/projects/openrao and pull requests are built and previewed automatically.
+
+### Readthedocs & Sphinx
+The website is hosted on [readthedocs](https://readthedocs.org/). The build workflow requires a configuration file: 
+[.readthedocs.yml](./.readthedocs.yml). This platform presents many advantages,
+thanks to its workflow of automatic branch/tag building & publication:
+- Multiple versions are activated: you can browse different versions of the documentation for different releases of OpenRAO
+- Pull requests are built automatically and the build status is reported in the PR's checks (["Build documentation" workflow](../.github/workflows/build_doc.yml)).  
+  Reviewers have access to the resulting documentation preview in order to make reviewing it easier.
+
+HTML content of the website is built automatically from source files written in [Markdown](https://fr.wikipedia.org/wiki/Markdown),
+using [Sphinx](https://www.sphinx-doc.org/).  
+Sphinx build needs a configuration file: [conf.py](./conf.py). 
+It contains all customization options for the website (for example, the theme used is [furo](https://pradyunsg.me/furo/)).
+Here is the most common cases when you'll need to tweak this file:
+- If you want to customize the theme's behaviour, you will probably have to change the conf.py file (refer to the
+  used theme's documentation first)
+- If you want to customize sphinx's behaviour, add plugins, css, etc., you need to change this file (refer to the
+  Sphinx doc first)
+
+### Customization options
+
+Sometimes, the possibilities offered by Sphinx & the used theme can be limiting. Sphinx offers the possibility to use
+custom html & css code. Currently, two methods are used:
+- Custom CSS: the [styles.css](_static/styles/styles.css) files contains custom CSS classes (read more about this [here](https://docs.readthedocs.io/en/stable/guides/adding-custom-css.html)).
+  Feel free to add classes to it if you find it necessary.
+- HTML overrides: the [_templates](_templates) directory contains HTML files that override objects inherited from Sphinx
+  or its theme (read more about this [here](https://www.sphinx-doc.org/en/master/development/theming.html#templating)).
+  You can use this method when other, lighter methods (i.e. tweaking mkdocs.yml & CSS styles) are not enough.
 
 ### Building the website locally
 
-In order to build the docs locally, run the following commands:  
+When modifying the website content, you can easily preview the result on your PC by navigating to the root of the
+project and running:
 ~~~bash
 pip install -r docs/requirements.txt
 sphinx-build -a docs ./build-docs
 ~~~
 Then open `build-docs/index.html` in your browser.  
 
-### Other information
-
-Relevant links:
-- We use Sphinx to build HTML pages: [Sphinx documentation](https://www.sphinx-doc.org/en/master/)
+### External links
+- [Readthedocs documentation](https://docs.readthedocs.io/en/stable/index.html)
+- [Sphinx documentation](https://www.sphinx-doc.org/en/master/)
 - Sphinx uses MyST to parse MD & RST files: [MyST documentation](https://mystmd.org/guide)
-- We Furo theme for Sphinx: [Furo documentation](https://pradyunsg.me/furo/)
+- [Furo documentation](https://pradyunsg.me/furo/)