Doc: use Markdown format instead of RST for various README files.

CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# Contributing Guidelines
+
+We're really glad you're reading this, because we need volunteer developers to
+expand this project. Here are some important resources to communicate with us:
+
+- [The official website](http://aff3ct.github.io),
+- Bugs? [Report issues on GitHub](https://github.com/aff3ct/aff3ct/issues).
+
+## Submitting changes
+
+Please send a
+[GitHub Pull Request to AFF3CT](https://github.com/aff3ct/aff3ct/pull/new/)
+with a clear list of what you've done (read more about
+[pull requests](https://help.github.com/articles/about-pull-requests/)). Please
+make your modifications on the ``development`` branch, any pull to the
+``master`` branch will be refused (the ``master`` is dedecated to the releases).
+
+Always write a clear log message for your commits. One-line messages are fine
+for small changes, but bigger changes should look like this:
+
+```bash
+git commit -m "A brief summary of the commit
+>
+> A paragraph describing what changed and its impact."
+```
+
+## Regression Testing
+
+We maintain a database of BER/FER reference simulations. Please give us some new
+references which solicit the code you added. We use those references in
+[an automated regression test script](https://github.com/aff3ct/aff3ct/blob/master/ci/test-regression.py).
+To propose new references please use our
+[dedicated repository](https://github.com/aff3ct/error_rate_references) and send
+us a pull request on it.
+
+## Coding conventions
+
+Start reading our code and you'll get the hang of it. For the readability, we
+apply some coding conventions:
+
+- we indent using tabulation (hard tabs),
+- we ALWAYS put spaces after list items and method parameters (``[1, 2, 3]``,
+  not ``[1,2,3]``), around operators (``x += 1``, not ``x+=1``), and around
+  hash arrows,
+- we use the [snake case](https://en.wikipedia.org/wiki/Snake_case)
+  (``my_variable``, not ``myVariable``), classes start with an upper case
+  (`My_class`, not `my_class`) and variables/methods/functions start with a
+  lower case,
+- the number of characters is limited to 120 per line of code.
+
+This is open source software. Consider the people who will read your code, and
+make it look nice for them. It's sort of like driving a car: Perhaps you love
+doing donuts when you're alone, but with passengers the goal is to make the ride
+as smooth as possible.

README.md

@@ -0,0 +1,93 @@
+# AFF3CT: A Fast Forward Error Correction Toolbox!
+
+[![GitLab Pipeline Status](https://img.shields.io/gitlab/pipeline/aff3ct/aff3ct.svg)](https://gitlab.com/aff3ct/aff3ct/pipelines)
+[![SonarQube Code Coverage](https://gitlab.com/aff3ct/aff3ct/badges/master/coverage.svg)](https://sonarqube.bordeaux.inria.fr/sonarqube/dashboard?id=storm%3Aaff3ct%3Agitlab%3Amaster)
+[![Documentation Build Status](https://img.shields.io/readthedocs/aff3ct.svg)](https://readthedocs.org/projects/aff3ct/)
+[![Latest Release](https://img.shields.io/github/release/aff3ct/aff3ct.svg)](https://github.com/aff3ct/aff3ct/releases)
+[![DOI](https://zenodo.org/badge/60615913.svg)](https://zenodo.org/badge/latestdoi/60615913)
+[![License: MIT](https://img.shields.io/github/license/aff3ct/aff3ct.svg)](./LICENSE)
+
+**AFF3CT** is a simulator dedicated to the Forward Error Correction (FEC or
+**channel coding**). It is written in **C++** and it supports a large range of
+codes: from the well-spread **Turbo codes** to the very new **Polar codes**
+including the **Low-Density Parity-Check (LDPC) codes**. **AFF3CT** is a command
+line program and it simulates communication chains based on a Monte Carlo
+method.
+
+It is very easy to use, for instance, to estimate the BER/FER decoding
+performances of the (2048,1723) Polar code from 1.0 to 4.0 dB:
+
+```bash
+aff3ct -C "POLAR" -K 1723 -N 2048 -m 1.0 -M 4.0 -s 1.0
+```
+
+And the output will be:
+
+```bash
+# ----------------------------------------------------
+# ---- A FAST FORWARD ERROR CORRECTION TOOLBOX >> ----
+# ----------------------------------------------------
+# Parameters :
+# [...]
+#
+# The simulation is running...
+# ---------------------||------------------------------------------------------||---------------------
+#  Signal Noise Ratio  ||   Bit Error Rate (BER) and Frame Error Rate (FER)    ||  Global throughput
+#         (SNR)        ||                                                      ||  and elapsed time
+# ---------------------||------------------------------------------------------||---------------------
+# ----------|----------||----------|----------|----------|----------|----------||----------|----------
+#     Es/N0 |    Eb/N0 ||      FRA |       BE |       FE |      BER |      FER ||  SIM_THR |    ET/RT
+#      (dB) |     (dB) ||          |          |          |          |          ||   (Mb/s) | (hhmmss)
+# ----------|----------||----------|----------|----------|----------|----------||----------|----------
+       0.25 |     1.00 ||      104 |    16425 |      104 | 9.17e-02 | 1.00e+00 ||    4.995 | 00h00'00
+       1.25 |     2.00 ||      104 |    12285 |      104 | 6.86e-02 | 1.00e+00 ||   13.678 | 00h00'00
+       2.25 |     3.00 ||      147 |     5600 |      102 | 2.21e-02 | 6.94e-01 ||   14.301 | 00h00'00
+       3.25 |     4.00 ||     5055 |     2769 |      100 | 3.18e-04 | 1.98e-02 ||   30.382 | 00h00'00
+# End of the simulation.
+```
+
+## Features
+
+**The simulator targets high speed simulations** and extensively uses parallel
+techniques like SIMD, multi-threading and multi-nodes programming models.
+Below, a list of the features that motivated the creation of the simulator:
+
+1. **reproduce state-of-the-art decoding performances**,
+2. **explore various channel code configurations**, find new trade-offs,
+3. **prototype hardware implementation** (fixed-point receivers, hardware in
+   the loop tools),
+4. **reuse tried and tested modules** and add yours,
+5. **alternative to MATLAB**, if you seek to reduce simulations time.
+
+## Installation
+
+First make sure to have installed a C++11 compiler, CMake and Git. Then install
+AFF3CT by running:
+
+```bash
+git clone --recursive https://github.com/aff3ct/aff3ct.git
+mkdir aff3ct/build
+cd aff3ct/build
+cmake .. -DCMAKE_BUILD_TYPE="Release"
+make -j4
+```
+
+## Contribute
+
+- [Source Code](https://github.com/aff3ct/aff3ct)
+- [Contributing guidelines](./CONTRIBUTING.md)
+
+## Support
+
+If you are having issues, please let us know on our
+[issue tracker](https://github.com/aff3ct/aff3ct/issues).
+
+## License
+
+The project is licensed under the MIT license.
+
+External Links
+--------------
+
+- [Official website](https://aff3ct.github.io)
+- [Documentation](https://aff3ct.readthedocs.io)

doc/sphinx/README.md

@@ -0,0 +1,19 @@
+# AFF3CT Documentation Generation
+
+**AFF3CT** uses [Sphinx](http://www.sphinx-doc.org) to generate the documentation.
+
+Install Sphinx using Python and pip:
+
+```bash
+sudo apt install python3 python3-pip
+sudo pip3 install -r requirements.txt
+```
+
+To generate the documentation, you simply have to do:
+
+```bash
+make html
+```
+
+The last command will create a new folder: `build/html`.
+In the `html` folder you just have to open the `index.html` file to read the generated documentation.

doc/sphinx/requirements.txt

@@ -2,4 +2,5 @@ Sphinx==1.8.1
 sphinx-rtd-theme==0.4.2
 sphinxcontrib-bibtex==0.4.0
 sphinxcontrib-websupport==1.1.0
-breathe==4.11.0
+breathe==4.11.0
+m2r==0.2.1

doc/sphinx/source/conf.py

@@ -46,7 +46,8 @@
     'sphinx.ext.autodoc',
     'sphinx.ext.mathjax',
     'sphinxcontrib.bibtex',
-    'breathe'
+    'breathe',
+    'm2r'
 ]
 
 # Add any paths that contain templates here, relative to this directory.

doc/sphinx/source/developer/contributing/contributing.rst

@@ -1,3 +1,3 @@
 .. _developer_contributing:
 
-.. include:: ../../../../../CONTRIBUTING.rst
+.. mdinclude:: ../../../../../CONTRIBUTING.md

doc/sphinx/source/others/readme/readme.rst

@@ -3,4 +3,4 @@
 Readme
 ^^^^^^
 
-.. include:: ../../../../../README.rst
+.. mdinclude:: ../../../../../README.md