Review: Testbeches doc

Remove trailing whitespace. Use new shell directive for bash code blocks. Rename testbenches_coding_guidelines to coding_guidelines because it is under testbenches already. On the templates, add the info to the write as reST comments, like: .. This is a comment Update ref- to external syntax. Update conf.py to reflect shell directive version requirement and fixup repository var value. Signed-off-by: Jorge Marques <[email protected]> Signed-off-by: Stanca Pop <[email protected]>
analogdevicesinc · Oct 14, 2024 · aeb4855 · aeb4855
1 parent dd9d5a8
commit aeb4855
Show file tree

Hide file tree

Showing 20 changed files with 102 additions and 96 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -1,6 +1,6 @@
 # -- Project information ------------------------------------------------------
 
-repository = 'hdl'
+repository = 'testbenches'
 project = 'Testbenches'
 copyright = '2024, Analog Devices, Inc.'
 author = 'Analog Devices, Inc.'
@@ -14,7 +14,7 @@
 ]
 
 needs_extensions = {
-    'adi_doctools': '0.3'
+    'adi_doctools': '0.3.47'
 }
 
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

diff --git a/docs/index.rst b/docs/index.rst
@@ -3,7 +3,7 @@ HDL Testbenches
 
 .. attention::
 
-   Work-in-progress, not all content has been imported yet.
+   Work-in-progress, not all content has been included yet.
 
 .. image:: sources/HDL_logo.svg
    :align: center
@@ -24,4 +24,4 @@ Contents
 
    user_guide/index
    library/index
-   projects/index
+   testbenches/index
diff --git a/docs/library/adi_vip/adi_vip_template/index.rst b/docs/library/adi_vip/adi_vip_template/index.rst
@@ -4,7 +4,7 @@ ADI VIPs
 ================================================================================
 
 Description
-	
+
 Features
 --------------------------------------------------------------------------------
 

diff --git a/docs/library/adi_vip/index.rst b/docs/library/adi_vip/index.rst
@@ -8,5 +8,5 @@ Contents
 
 .. toctree::
    :maxdepth: 2
-   
+
    ADI VIP Template <adi_vip_template/index>
diff --git a/docs/library/custom_ip/custom_ip_template/index.rst b/docs/library/custom_ip/custom_ip_template/index.rst
@@ -4,7 +4,7 @@ ADI VIP
 ================================================================================
 
 Description
-	
+
 Features
 --------------------------------------------------------------------------------
 

diff --git a/docs/library/custom_ip/index.rst b/docs/library/custom_ip/index.rst
@@ -8,5 +8,5 @@ Contents
 
 .. toctree::
    :maxdepth: 2
-   
+
    Custom IP Template <custom_ip_template/index>
diff --git a/docs/library/index.rst b/docs/library/index.rst
@@ -10,22 +10,22 @@ ADI VIP
    :maxdepth: 1
 
    adi_vip/index
-   
+
 Custom IP
 -------------------------------------------------------------------------------
 
 .. toctree::
    :maxdepth: 1
 
    custom_ip/index
-   
+
 Utilities
 -------------------------------------------------------------------------------
 
 .. toctree::
    :maxdepth: 1
 
-   utilities/index     
+   utilities/index
 
 Xilinx VIP
 -------------------------------------------------------------------------------
@@ -34,4 +34,4 @@ Xilinx VIP
    :maxdepth: 1
 
    xilinx_vip/index
-     
+
diff --git a/docs/library/utilities/index.rst b/docs/library/utilities/index.rst
@@ -8,7 +8,7 @@ Contents
 
 .. toctree::
    :maxdepth: 2
-   
+
    Monitor <monitor/index>
    Scoreboard <scoreboard/index>
    Watchdog <watchdog/index>
diff --git a/docs/library/xilinx_vip/index.rst b/docs/library/xilinx_vip/index.rst
@@ -8,9 +8,9 @@ Contents
 
 .. toctree::
    :maxdepth: 2
-   
+
    AXI VIP <axi_vip/index>
    AXIS VIP <axis_vip/index>
    Clock VIP <clk_vip/index>
    Reset VIP <rst_vip/index>
-   
+
diff --git a/docs/testbenches/index.rst b/docs/testbenches/index.rst
@@ -24,4 +24,4 @@ Project Based Testbenches
    :maxdepth: 1
 
    project_based/index
- 
+
diff --git a/docs/testbenches/ip_based/template/index.rst b/docs/testbenches/ip_based/template/index.rst
@@ -45,6 +45,6 @@ Test stimulus
 Resources
 -------------------------------------------------------------------------------
 
-.. include:: ../common/more_information.rst
+.. include:: ../../common/more_information.rst
 
-.. include:: ../common/support.rst
+.. include:: ../../common/support.rst
diff --git a/docs/testbenches/project_based/ad7616/index.rst b/docs/testbenches/project_based/ad7616/index.rst
@@ -1,4 +1,4 @@
-orphan:
+:orphan:
 
 .. _ad7616:
 

diff --git a/docs/testbenches/project_based/template/index.rst b/docs/testbenches/project_based/template/index.rst
@@ -12,10 +12,12 @@ Block design
 Block diagram
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-\*\* MUST: Use SVG format for the diagram \*\*
+..
+   MUST: Use SVG format for the diagram
 
-\*\* TIP: Block diagrams should contain subtitles only if there are at least two
-different diagrams \*\*
+..
+   TIP: Block diagrams should contain subtitles only if there are at least two
+   different diagrams
 
 .. image:: ../template/project_based_template_bd.svg
    :width: 800
@@ -25,7 +27,8 @@ different diagrams \*\*
 Configuration parameters and modes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-\**\* MENTION IF ANY MODES ARE AVAILABLE FOR CONFIGURATION \**\*
+..
+   MENTION IF ANY MODES ARE AVAILABLE FOR CONFIGURATION
 
 Build parameters
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -37,18 +40,19 @@ The following are the parameters of this project that can be configured:
 -  NUM_OF_SDI: defines the number of MOSI lines of the SPI interface:
    Options: 1 - Interleaved mode, 2 - 1 lane per channel,
    4 - 2 lanes per channel, 8 - 4 lanes per channel
--  CAPTURE_ZONE: defines the capture zone of the next sample. 
+-  CAPTURE_ZONE: defines the capture zone of the next sample.
    There are two capture zones: 1 - from negative edge of the BUSY line
    until the next CNV positive edge -20ns, 2 - from the next consecutive CNV
    positive edge +20ns until the second next consecutive CNV positive edge -20ns
 -  DDR_EN: defines the type of data transfer. In echo and master clock mode
    the SDI lines can have Single or Double Data Rates.
    Options: 0 - MISO runs on SDR, 1 - MISO runs on DDR.
-   
+
 Configuration files
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-\**\* MENTION IF ANY CONFIGURATION FILES ARE AVAILABLE FOR TESTS \**\*
+..
+   MENTION IF ANY CONFIGURATION FILES ARE AVAILABLE FOR TESTS
 
 The following are available configurations for the test bench:
 
@@ -70,44 +74,46 @@ The following are available configurations for the test bench:
    | cfg_cm1_sdi2_cz2_ddr0 | 1        | 2          | 2            | 0      |
    +-----------------------+----------+------------+--------------+--------+
    | cfg_cm1_sdi2_cz2_ddr1 | 1        | 2          | 2            | 1      |
-   +-----------------------+----------+------------+--------------+--------+ 
+   +-----------------------+----------+------------+--------------+--------+
    | cfg_cm1_sdi4_cz2_ddr0 | 1        | 4          | 2            | 0      |
-   +-----------------------+----------+------------+--------------+--------+ 
+   +-----------------------+----------+------------+--------------+--------+
    | cfg_cm1_sdi4_cz2_ddr1 | 1        | 4          | 2            | 1      |
-   +-----------------------+----------+------------+--------------+--------+ 
+   +-----------------------+----------+------------+--------------+--------+
    | cfg_cm1_sdi8_cz2_ddr0 | 1        | 8          | 2            | 0      |
-   +-----------------------+----------+------------+--------------+--------+ 
+   +-----------------------+----------+------------+--------------+--------+
    | cfg_cm1_sdi8_cz2_ddr1 | 1        | 8          | 2            | 1      |
    +-----------------------+----------+------------+--------------+--------+
-   
+
 Tests
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-\**\* MENTION IF ANY MODES ARE AVAILABLE FOR TESTS \**\*
+..
+   MENTION IF ANY MODES ARE AVAILABLE FOR TESTS
 
 The following test program files are available:
 
 =============== ==========================================
 Test program    Usage
 =============== ==========================================
 test_program_si Tests the parallel interface capabilities.
-test_program_pi Tests the serial interface capabilities.  
+test_program_pi Tests the serial interface capabilities.
 =============== ==========================================
 
 Available configurations & tests combinations
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 ============= =============== ===================================
-Configuration Test            Build command 
+Configuration Test            Build command
 ============= =============== ===================================
 cfg_si        test_program_si make CFG=cfg_si TST=test_program_si
-cfg_pi        test_program_pi make CFG=cfg_pi TST=test_program_pi 
+cfg_pi        test_program_pi make CFG=cfg_pi TST=test_program_pi
 ============= =============== ===================================
 
 .. warning::
-    Mixing a wrong pair of CFG and TST will result in a building errror. 
+
+    Mixing a wrong pair of CFG and TST will result in a building errror.
     Please checkout the proposed combinations before running a custom test.
-    
+
 Clock scheme
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -135,46 +141,44 @@ the HDL repository, and then build the project as follows:.
 Build all the possible combinations of tests and configurations, using only the
 command line.
 
-.. code-block::
-   :linenos:
+.. shell::
+   :showuser:
 
-   user@analog:~$ cd testbenches/ad7616
-   user@analog:~/hdl/projects/ad7616$ make
+   $cd testbenches/ad7616
+   $make
 
 *Example 2*
 
 Build all the possible combinations of tests and configurations, using the
 Vivado GUI. This command will launch Vivado, will run the simulation and display
 the waveforms.
 
-.. code-block::
-   :linenos:
+.. shell::
+   :showuser:
 
-   user@analog:~$ cd testbenches/ad7616
-   user@analog:~/hdl/projects/ad7616/$ make MODE=gui
+   $cd testbenches/ad7616
+   $make MODE=gui
 
 *Example 3*
 
 Build a particular combination of test and configuration, using the Vivado GUI.
 This command will launch Vivado, will run the simulation and display the
 waveforms.
 
-.. code-block::
-   :linenos:
+.. shell::
+   :showuser:
 
-   user@analog:~$ cd testbenches/ad7616
-   user@analog:~/hdl/projects/ad7616$ make MODE=gui CFG=cfg_pi TST=test_program_pi
+   $cd testbenches/ad7616
+   $make MODE=gui CFG=cfg_pi TST=test_program_pi
 
 The built projects can be found in the ``runs`` folder, where each configuration specific
-build has it's own folder named after the configuration file's name. 
+build has it's own folder named after the configuration file's name.
 Example: if the following command was run for a single configuration in the clean folder
 (no runs folder available):
 
-if the following command was run
-
 ``make CFG=cfg_pi``
 
-then the subfolder under ``runs`` name will be:
+Then the subfolder under ``runs`` name will be:
 
 ``cfg_pi``
 
@@ -184,6 +188,6 @@ Test stimulus
 Resources
 -------------------------------------------------------------------------------
 
-.. include:: ../common/more_information.rst
+.. include:: ../../common/more_information.rst
 
-.. include:: ../common/support.rst
+.. include:: ../../common/support.rst
diff --git a/docs/user_guide/architecture.rst b/docs/user_guide/architecture.rst
@@ -20,7 +20,7 @@ Project files for test benches
     -   ``utilities`` --- ADI Utilities
     -   ``xilinx_vip`` --- Xilinx VIPs
 
--  ``scripts`` --- used for creating and running the testbenches        
+-  ``scripts`` --- used for creating and running the testbenches
 
 -  ``testbenches``
 
@@ -82,7 +82,7 @@ Requirements:
 Process:
 
 -  Create a ``new configuration`` in ``cfg`` folder.
--  Check if the ``Makefile`` automatically includes the newly created ``configuration``, 
+-  Check if the ``Makefile`` automatically includes the newly created ``configuration``,
    otherwise add it to the list manually.
 -  If a ``new parameter`` needs to be added, make sure all of the other ``configuration``
    files are updated with the new parameter name and a new value as well
@@ -104,7 +104,7 @@ Requirements:
 Process:
 
 -  Create a ``new test program`` in tests folder.
--  Check if the ``Makefile`` automatically includes the newly created 
+-  Check if the ``Makefile`` automatically includes the newly created
    ``configuration``, otherwise add it to the list manually.
 -  Test the program with the existing configurations.
 
@@ -123,7 +123,7 @@ Process:
 
 -  Create a new parameter that tells the ``system_bd.tcl`` what to build.
         -   this parameter must be included in all of the existing and new
-            configuration files; 
+            configuration files;
         -   if the design already has multiple variations of the block design,
             update the existing parameter with the new value which corresponds
             to the new block design
@@ -136,4 +136,4 @@ Process:
    and add the test program:config options to the list that you want to run.
 -  In the ``system_project.tcl`` add a switch that chooses between the test programs
    based on the parameter.
--  Write and test the new ``test program``.
+-  Write and test the new ``test program``.