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

@@ -79,7 +79,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 Snitch [tutorial](tutorial.md).
 
 ```
 ## Performance metrics
@@ -104,7 +104,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 can also be dumped to a JSON file for further processing (see [gen_trace.py](https://github.com/pulp-platform/{{ repo }}/blob/{{ branch }}/util/trace/gen_trace.py)).
 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                                                                                                                                                                                         |