add build docs in test suite.

.github/workflows/test.yml

@@ -50,3 +50,25 @@ jobs:
       - name: Codespell
         if: always()
         uses: codespell-project/actions-codespell@v2
+
+  build-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python }}
+          cache: 'pip'
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[dev,doc]
+      - name: Build the doc with sphinx
+        run: |
+          python -m sphinx build docs docs_build
+      - name: Upload documentation artifact
+        uses: actions/upload-artifact@v2
+        with:
+          name: docs
+          path: docs_build

docs/explanations/snake-internal.md

@@ -61,6 +61,31 @@ Since the acquisition of a shot can be fully determined from the instant it is r
 The MRD (or ismrmrd) format is a standard format for storing MRI raw k-space data. It basically consist in a HDF5 file with a dedicated header and a specific structure. 
 :::
 
+SNAKE relies on the `.mrd` file format to store the raw data from MRI experiments.
+
+The `.mrd` file format is a standard for sharing raw data of MRI experiments. 
+The format is based on the HDF5 file format, which is a widely used file format for scientific data. 
+The `.mrd` file format is designed to store raw data from MRI experiments, including the raw k-space data, the acquisition parameters, and other relevant information [^1]
+The format is designed to be flexible and extensible, allowing for the storage of a wide range of data types and structures. 
+
+[^1]: https://ismrmrd.readthedocs.io/en/latest/index.html 
+
+#### SNAKE MRD file structure 
+
+SNAKE leverages the flexibility of the `.mrd` file format to store all the information need to simulate (f)MRI experiments. 
+This allows the simulation to be performed in parallel (and very fast). 
+
+The SNAKE MRD file structure is as follows: 
+
+ - `header` group: contains the metadata for the file, as well as serialized information for the simulation. 
+ - `acquisition` group: contains the raw k-space data and the acquisition parameters. 
+ - `images` group: contains the static information for the simulation (phantom, coil sensitivity maps, etc.).
+ - `waveforms` group: contains the dynamic information for the simulation (motion, physiological noise, etc.).
+
+#### Reading and writing MRD files
+
+SNAKE provides a set of functions to read and write MRD files in the `snake.mrd_utils` module, built on top of the [`ismrmrd`](https://github.com/ismrmrd/ismrmrd-python) library. 
+
 ### Efficient computations with Multiprocessing
 
 to perform the acquisition SNAKE efficiently use the multiprocessing python module to parallelize the acquisition of the k-space data. See [](#snake.engine.BaseEngine.__call__) for more details.

docs/index.md

@@ -104,3 +104,13 @@ auto_scenarios/index
 auto_api/snake/snake.core.rst
 auto_api/snake/snake.toolkit.rst
 ```
+
+
+```{toctree}
+:hidden:
+:caption: Miscellaneous
+
+misc/contributors
+misc/development
+misc/license
+```