Fix docs (#613)

* Fix typo * Add make to prerequisites * Fix minor doc errors * Update documentation instructions
esl-epfl · Dec 20, 2024 · e4c8c26 · e4c8c26
1 parent 44bd1ed
commit e4c8c26
Show file tree

Hide file tree

Showing 8 changed files with 42 additions and 33 deletions.
diff --git a/docs/source/How_to/CompileMakefile.md b/docs/source/How_to/CompileMakefile.md
@@ -70,7 +70,7 @@ This will create the executable file to be loaded in your target system (ASIC, F
 Remember that, `X-HEEP` is using CMake to compile and link. Thus, the generated files after having
 compiled and linked are under `sw\build`
 
-## FreeROTS based applications
+## FreeRTOS based applications
 
 'X-HEEP' supports 'FreeRTOS' based applications. Please see `sw\applications\example_freertos_blinky`.
 

diff --git a/docs/source/How_to/GettingStarted.md b/docs/source/How_to/GettingStarted.md
@@ -33,7 +33,7 @@ All the command listed in the README can be execute in the docker container, exc
 To use `X-HEEP`, first make sure you have the following apt packages, or install them as:
 
 ```bash
-sudo apt install lcov libelf1 libelf-dev libftdi1-2 libftdi1-dev libncurses5 libssl-dev libudev-dev libusb-1.0-0 lsb-release texinfo autoconf cmake flex bison libexpat-dev gawk tree xterm python3-venv python3-dev
+sudo apt install lcov libelf1 libelf-dev libftdi1-2 libftdi1-dev libncurses5 libssl-dev libudev-dev libusb-1.0-0 lsb-release texinfo autoconf make cmake flex bison libexpat-dev gawk tree xterm python3-venv python3-dev
 ```
 
 In general, have a look at the [Install required software](https://opentitan.org/guides/getting_started/index.html) section of the OpenTitan documentation.

diff --git a/docs/source/How_to/UpdateDocumentation.md b/docs/source/How_to/UpdateDocumentation.md
@@ -1,27 +1,26 @@
 # Update the documentation
 
-All documentation is found in the `/docs` directory.
+All documentation is found in the `/docs` directory. Thank you for helping keep X-HEEP accurately and extensively documented!
 
 1. If you need to create a new entry, add the new document in markdown (`.md` extension) to the corresponding folder. Otherwise, just edit the corresponding file.
 
 > Make sure the document has one single `# header`, otherwise they will be considered different documents.
 
-2. If a new folder is added, add it to the `toctree` inside `docs/source/index.rst` (as the `peripherals` folder is)
-3. Commit and push
+2. If a new folder is added, add it to the `toctree` inside `docs/source/index.rst` (as the `peripherals` folder is).
+3. Commit and push.
+4. Open a pull request and you can preview the updates to the docs in the CI build.
+5. Once the pull request is merged, the documentation will be updated automatically.
 
-## Refresh the web documentation
+## Build locally the web documentation
 
-After each change to the documentation, once the branch is merged into the main branch of X-HEEP, anyone must do the following:
+If you want to build the web documentation locally to test or debug the build:
 
 1. Open a terminal in the `docs` folder and make sure the conda environment is activated.
-2. If it is your first time updating the web docs, run:
+2. The first time you do this, run:
 ```bash
 pip install -r requirements.txt
 ```
-3. Run
+3. Run:
 ```bash
 make clean html
 ```
-4. Wait a few minutes and enjoy your brand new documentation in [Read the Docs](https://x-heep.readthedocs.io/en/latest/).
-
-Thank you for helping keep X-HEEP accurately and extensively documented!
diff --git a/docs/source/Peripherals/DMA.md b/docs/source/Peripherals/DMA.md
@@ -26,7 +26,7 @@ The DMA **SDK**, on the other hand, offers user-friendly functions for essential
 
 <p  align="center">Figure 1: Structure of the DMA subsystem in X-Heep </p>
 
-#### DMA channels layout
+### DMA channels layout
 
 The DMA subsystem is composed of a parametrized number of control units called **channels**. 
 Each channel can be configured, by the CPU or by an external controller, to perform a *transaction*, independently of the state of other channels.
@@ -52,7 +52,7 @@ While the 1st solution is a general purpose, balanced configuration, the 2nd sol
 This mechanism guarantees **maximum flexibility**, enabling the user to adapt the DMA subsystem to its requirements, both in terms of area and performance.
 <br>
 
-#### Interrupts
+### Interrupts
 
 If enabled, a transaction interrupt is raised every time a DMA transaction is completed. However, due to architectural limitations, there is only a single transaction done signal for the entire DMA subsystem.
 
@@ -64,7 +64,7 @@ It is possible that a channel could raise an interrupt while the CPU is processi
 
 For this reason, the handler implemented by the user should be as brief as possible.
 
-#### Data FIFOs configuration
+### Data FIFOs configuration
 
 Each DMA channel uses FIFOs to buffer the data to be read and written, which is crucial for mitigating the combined delays from the system bus and the Always On Peripheral Bus (**AOPB**). 
 
@@ -96,7 +96,7 @@ Now, let's set the first 2 channels, CH0 and CH1, to the large size, CH2 to smal
 
 <br>
 
-#### Triggers
+### Triggers
 
 In the case of memory-peripheral operations, it is common for the peripheral to have a reaction time that cannot match the system clock. For example, the SPI trasmits data with a period of circa 30 clock cycles. 
 
@@ -107,7 +107,7 @@ The DMA can be configured to respond to triggers by enabling the appropriate _sl
 
 <br>
 
-#### Tips for DMA-based accelerator developers
+### Tips for DMA-based accelerator developers
 
 The DMA subsystem has been developed with specific features to facilitate the creation of custom accelerators that can leverage it to improve memory-intense applications.
 
@@ -132,7 +132,7 @@ Additional documentation can be found in the **VerifHEEP documentation**, but in
   - Analyze the performance of the tests. 
 <br>
 
-### Registers description
+## Registers description
 
 This section will describe every register of a DMA channel and their function.
 The complete addres of a DMA channel register is the following:

diff --git a/docs/source/Peripherals/SPI.md b/docs/source/Peripherals/SPI.md
@@ -1189,7 +1189,7 @@ checks wherever needed.
 
 A performance testing was carried out utilizing the _EPFL Programmer_, which includes
 a _W25Q128JW_ flash memory, and the _PYNQ-Z2_ FPGA. The 
-[SPI Flash Loading Boot Procedure](/How_to/ExecuteFromFlash.html#spi-flash-loading-boot-procedure)
+[SPI Flash Loading Boot Procedure](../How_to/ExecuteFromFlash.md#spi-flash-loading-boot-procedure)
 was employed for all tests.
 
 The test application used the 

diff --git a/docs/source/Verification/VerifHEEP.md b/docs/source/Verification/VerifHEEP.md
@@ -20,7 +20,7 @@ Additionally, the EPFL programmer will be used for serial communication with the
 
 ## Methods description
 
-#### <i> __init__ </i>
+### <i> __init__ </i>
 
 _Purpose_:
 The initialization function is used to create the VerifHeep object. During this process, it's required to indicate the target of the verification and its directory. Furthermore, an optimization flag can be set when synthesis or simulation module building will be performed.
@@ -33,7 +33,7 @@ _Parameters_:
 - **xheep_dir**: Sets the directory of the X-Heep project, necessary to run scripts.
 - **opt_en**: By default set to _false_, this flag indicates whether optimization should be performed when building the simulation model. Available **only** with QuestaSim!
 
-#### <i> compileModel </i>
+### <i> compileModel </i>
 
 _Purpose_:
 This method is used to compile a simulation model for both Verilator and QuestaSim, i.e. run _make mcu-gen_, provided they are properly installed on the host system.
@@ -43,7 +43,7 @@ _Parameters_:
 - **cpu**: By default set to `cv32e40px`, this flags indicates which CPU will be included in the model.
 - **bus**: By default set to `1toN`, this flag indicates the bus type.
 
-#### <i> buildModel </i>
+### <i> buildModel </i>
 
 _Purpose_:
 This method is used to either build a simulation model for Verilator or QuestaSim or to synthesize the project with Xilinx Vivado, provided they are properly installed on the host system.
@@ -53,7 +53,7 @@ _Parameters_:
 - **cpu**: By default set to `cv32e40px`, this flags indicates which CPU will be included.
 - **bus**: By default set to `1toN`, this flag indicates the bus type.
 
-#### <i> serialBegin </i>
+### <i> serialBegin </i>
 
 _Purpose_:
 This method is used to set up the serial communication with the _pynq-z2_ FPGA board.
@@ -68,7 +68,7 @@ _Parameters_:
 _Return value_:
 - **Outcome of the connection**, which is _False_ for unsuccessful.
 
-#### <i> setupDeb </i>
+### <i> setupDeb </i>
 
 _Purpose_:
 This method is used to set up the GDB debugger. It creates a process on which the debug communication will be run, thus making this function conveniently non-blocking. 
@@ -78,15 +78,15 @@ This method is used to set up the GDB debugger. It creates a process on which th
 _Parameters_:
 None
 
-#### <i> stopDeb </i>
+### <i> stopDeb </i>
 
 _Purpose_:
 This method is used to close the debugger. Useful both at the end of a script or during the cyclical reset of the debug connection, as explained before. 
 
 _Parameters_:
 None
 
-#### <i> genInputDataset </i>
+### <i> genInputDataset </i>
 
 _Purpose_:
 This method is used to generate random data that the application can use to perform verification. It's possible to set the range of the data, the dimension of the array, the datatype and its variable identifier. In addition, it's possible to obtain a single _.h_ file or both a _.c_ and a _.h_ file.
@@ -101,7 +101,7 @@ _Parameters_:
 - **dataset_name**: Indicates the name of the dataset.
 - **datatype**: By default set to *uint32_t*, indicates the datatype of the array to be generated.
 
-#### <i> genGoldenResult </i>
+### <i> genGoldenResult </i>
 
 _Purpose_:
 This method is used to generate golden data from an input dataset, enabling applications to verify the functionality of a unit or accelerator. This feature is performed by a user-defined function, passed as a parameter, which processes the input data.
@@ -120,7 +120,7 @@ _Parameters_:
 - **golden_name**: Indicates the name of the golden result array.
 - **output_datatype**: By default set to *uint32_t*, indicates the datatype of the array to be computed.
 
-#### <i> modifyFile </i>
+### <i> modifyFile </i>
 
 _Purpose_:
 This method is simple yet very useful in particular situations. It allows the user to modify a row with a replacement of its choice. It can be used to modify _#define_ that could change the behaviour of the application.
@@ -133,14 +133,14 @@ _Parameters_:
 - **pattern**: Indicates the pattern to look for in the file, using the library **re**.
 - **replacement**: Indicates the row that will be put in place instead of the pattern found.
 
-#### <i> chronoStart/chronoStop </i>
+### <i> chronoStart/chronoStop </i>
 
 _Purpose_:This method is used to track the execution time of an iteration and, by extension, to estimate the total execution time of the verification process.
 
 _Parameters_:
 None
 
-#### <i> chronoExecutionEst </i>
+### <i> chronoExecutionEst </i>
 
 _Purpose_:This method estimates the total execution time of the verification process, assuming the verification consists of a loop with N iterations. It requires that the `_chronoStart_` method is called at the beginning and the `_chronoStop_` method is called at the end of each iteration.
 
@@ -153,7 +153,7 @@ _Return value_:
   - _"minutes"_
   - _"seconds"_
 
-#### <i> launchTest </i>
+### <i> launchTest </i>
 
 _Purpose_:
 This method is crucial in the verification process, as it's in charge of compiling the application, loading it on the FPGA using the scan chains and GDB, waiting for the results and storing then in *self.results*.

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -43,4 +43,7 @@
 
 apidoc_module_dir = '../../util/x_heep_gen'
 apidoc_output_dir = 'Configuration/generated'
-apidoc_separate_modules = True
+apidoc_separate_modules = True
+
+# Auto-generate header anchors for MyST
+myst_heading_anchors = 4
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -89,4 +89,11 @@ Index
    :caption: Configuration
 
    ./Configuration/*
-   ./Configuration/generated/modules.rst
+   ./Configuration/generated/modules.rst
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+   :caption: Verification
+
+   ./Verification/*