treewide: Update docs and tutorial

docs/ug/documentation.md

@@ -1,22 +1,23 @@
 # Documentation
 
-Documentation of the generator and related infrastructure is hosted under
-`docs`. Static `html` documentation is build from the latest `main` branch by
-the CI. We use [mkdocs](https://www.mkdocs.org/) together with the [material
-theme](https://squidfunk.github.io/mkdocs-material/). Before building the
-documentation, make sure you have the required dependencies installed:
+Documentation pages for the Snitch cluster are hosted under `docs`. Static
+`html` documentation is built and deployed from the latest `main` branch by the
+CI. We use [mkdocs](https://www.mkdocs.org/) together with the [material
+theme](https://squidfunk.github.io/mkdocs-material/).
 
-```shell
-pip install .
-```
-
-After everything is installed, you can build a static copy of the `html` documentation by
-executing (in the root directory):
+You can build a static copy of the `html` documentation by
+executing (in the root of this repository):
 
 ```shell
 make docs
 ```
 
+Documentation for the Python sources in this repository is generated from the
+docstrings contained within the sources themselves, using
+[mkdocstrings](https://mkdocstrings.github.io/).
+Documentation for the C sources in this repository is generated from the
+Doxygen-style comments within the sources themselves, using Doxygen.
+
 ## Organization
 
 The `docs` folder is organized as follows:

docs/ug/trace_analysis.md

@@ -2,10 +2,13 @@
 
 ## Trace generation
 
-During RTL simulation, the Snitch core complex (CC) dumps a wide set of information to the `logs/trace_hart_XXXXX.dasm` file (see [snitch_cc.sv](https://github.com/pulp-platform/snitch_cluster/blob/main/hw/snitch_cluster/src/snitch_cc.sv)), `XXXXX` denoting the index of the Snitch core in the system.
+During RTL simulation, the Snitch _core complex (CC)_ dumps a wide set of information to the `logs/trace_hart_XXXXX.dasm` file (see [snitch_cc.sv](https://github.com/pulp-platform/snitch_cluster/blob/main/hw/snitch_cluster/src/snitch_cc.sv)), `XXXXX` denoting the hart ID of the Snitch core in the system.
 
 The [gen_trace.py](../rm/trace/gen_trace.md) script can be used to elaborate this information into a human-readable form, and is invoked by the `make traces` target to generate `logs/trace_hart_XXXXX.txt`.
 
+!!! info
+    For more information on the topics covered in this page have a look inside the [gen_trace.py](https://github.com/pulp-platform/{{ repo }}/blob/{{ branch }}/util/trace/gen_trace.py) script.
+
 ## Trace walkthrough
 
 Here is an extract of a trace generated by the previous script:
@@ -79,7 +82,7 @@ One last note should be made about `frep` loops. While not visible from this tra
 
 ## Performance metrics
 
-Finally, at the end of the trace, a collection of performance metrics automatically computed from the trace is reported. The performance metrics are associated to regions defined in your code. More information on how to define these regions can be found in the Snitch [tutorial](../../target/snitch_cluster/README.md).
+Finally, at the end of the trace, a collection of performance metrics automatically computed from the trace is reported. The performance metrics are associated to regions defined in your code. More information on how to define these regions can be found in the [tutorial](tutorial.md#debugging-and-benchmarking).
 
 ```
 ## Performance metrics
@@ -104,7 +107,7 @@ cycles                                          87
 total_ipc                                   0.8046
 ```
 
-The trace will contain the most relevant performance metrics for manual inspection. These and additional performance metrics can also be dumped to a JSON file for further processing (see [gen_trace.py](../../util/trace/gen_trace.py)).
+The trace will contain the most relevant performance metrics for manual inspection. These and additional performance metrics are also dumped to a `.json` file for further processing.
 In the following table you can find a complete list of all the performance metrics extracted from the trace along with their description:
 
 |Metric                    |Description                                                                                                                                                                                         |