DOCS: updates focused on plugins.rst, but there were capitalization c…

…hanges done to the entire documentation by search and manual replace

CHANGELOG.md

@@ -2,6 +2,24 @@
 
 This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.24.2] -
+- Documentation consistency cleanup, changes are mostly aesthetic, the content is not changed:
+  - Expanding use of fixed width fonts for file, function, argument, variable, macro, ... names.
+  - Fixed missing capitalization and punctuation, mostly for lists.
+  - Capitalization of acronyms and proper nouns:
+    - python => Python,
+    - riscof => RISCOF,
+    - isa => ISA,
+    - platform => Platform,
+    - yaml => YAML,
+    - verilator => Verilator,
+    - cli => CLI,
+    - makefile => Makefile (depending on context),
+    - ...
+  - Few spelling and grammar fixes.
+  - Few instances where names in documentation did not match names in the source code.
+    This were either copy/paste errors or code changes not propagated to documentation.
+
 ## [1.24.1] - 2022-07-19
 - Account for the same test to be included with both XLEN variants in the isa generation.
 - Add markdown report for coverage statistics.

docs/source/TestFormatSpec.adoc

@@ -96,7 +96,7 @@ significant amount of the framework shall depend on the existence of these macro
   `RVTEST_ISA(isa_str)`::          
 
     - defines the Test Virtual Machine (TVM, the ISA being tested) +
-    - empty macro to specify the isa required for compilation of the test. +
+    - empty macro to specify the ISA required for compilation of the test. +
     - this is mandated to be present at the start of the test.
 
 

docs/source/arch-tests.rst

@@ -28,7 +28,7 @@ Setup all the DUT and Ref Plugins
      You will need the path of the `riscof-plugins` directory from the above repo for the next
      steps.
 
-  3. You will also need to create a riscof-plugin for you own DUT. If you haven't already done so,
+  3. You will also need to create a RISCOF plugin for you own DUT. If you haven't already done so,
      please refer to the :ref:`plugins` section for details on building one.
 
 Create a config.ini file

docs/source/commands.rst

@@ -16,8 +16,9 @@ The current list of subcommands includes:
 - ``testlist``
 - ``run``
 
-arch-tests
-----------
+``arch-tests``
+--------------
+
 This command is used to clone and update the tests from the official `riscv-arch-test <https://github.com/riscv/riscv-arch-test>`_ repository.
 
 This command requires one of the following flags to be specified from the CLI.
@@ -33,8 +34,8 @@ Optional arguments from the CLI:
 - ``--dir``: The path to the directory where the suite is to be cloned to. Defaults to
   ``./riscv-arch-test`` if skipped.
 
-coverage
---------
+``coverage``
+------------
 
 This command is used to collect the ISA coverage metrics of a given test-suite and generate a coverage
 report in html.
@@ -65,8 +66,8 @@ default web-browser.
 
 For a example on using this feature please refer to the :ref:`coverage` section.
 
-gendb
------
+``gendb``
+---------
 
 This command is used to generate a database YAML file for all tests available in the test-suite. The
 commands requires the following inputs from the CLI:
@@ -90,16 +91,16 @@ used by RISCOF to select and filter tests based on input DUT configuration.
    <https://github.com/riscv/riscv-arch-test/blob/master/spec/TestFormatSpec.adoc>`_ set forth
    by the riscv-arch-test SIG.
 
-setup
------
+``setup``
+---------
 
 The setup command is used to generate a series of Template files that are required by RISCOF. 
 These files are meant to provide ease to users integrating their DUT to RISCOF for the first time
 and should be modified by the users.
 
 The setup utility takes in the following optional inputs from the CLI:
 
-- ``--dutname``: The name of the dut for running the tests on. The utility will use this name to create a
+- ``--dutname``: The name of the DUT for running the tests on. The utility will use this name to create a
   template plugin directory with all the relevant files. These files will have to be modified by 
   the user. Defaults to ``spike`` when skipped.
 - ``--refname``: The name of the reference plugin to be used in RISCOF. The utility will use this name to
@@ -108,38 +109,38 @@ The setup utility takes in the following optional inputs from the CLI:
 
 The setup utility will also create a sample config.ini file using the above inputs.
 
-validateyaml
-------------
+``validateyaml``
+----------------
 
-This command simply performs a validation of the ISA spec and the platform pspec YAMLs of the DUT
+This command simply performs a validation of the ISA ``ispec`` and the platform ``pspec`` YAMLs of the DUT
 as mentioned in the ``config.ini`` using riscv-config. The outputs are checked for the version of the YAMLs in
 the directory pointed to by ``work_dir``.
 
-testlist
---------
+``testlist``
+------------
 
-This command is used to filter tests from the database.yaml based on the configuration of DUT
-present in the ISA and platform YAMLs as mentioned in the ``config.ini``. This command will require 
+This command is used to filter tests from the ``database.yaml`` based on the configuration of DUT
+present in the ISA and Platform YAMLs as mentioned in the ``config.ini``. This command will require 
 the following inputs from the CLI:
 
 - ``--suite``: The test suite from which the tests need to be filtered.
 
-This command takes the following optional inputs from CLI
+This command takes the following optional inputs from CLI:
 
 - ``--config``: The path to the ``config.ini`` file. Defaults to ``./config.ini`` if skipped.
 - ``--work-dir``: The path to the working directory where all artifacts need to be dumped. Defaults to
   ``./riscof_work``.
 
 The utility first creates a ``database.yaml`` for the input suite. For each test in the database YAML, 
 this utility will check if the conditions of any parts of a test are enabled based on the ISA and
-platform YAML specs of the DUT. If any part is enabled, then the corresponding test is entered into
+Platform YAML specs of the DUT. If any part is enabled, then the corresponding test is entered into
 the teslist along with the respective coverage labels and compile macros.
 
 The utility will dump the test list in the ``testlist.yaml`` file in the ``work_dir`` directory. This
 YAML will follow the same syntax as defined in the :ref:`testlist` section.
 
-run
----
+``run``
+-------
 
 This is probably the primary command of RISCOF which is going to be widely used. This command is
 currently responsible for first validating the inputs YAMLs, 
@@ -167,7 +168,7 @@ Optional arguments from the CLI:
 The ``work_dir`` is cleaned by default. However, if one of ``no-clean``, ``testfile`` or ``dbfile`` 
 are specified, it is preserved as is.
 
-All artifacts of this command are generated in the ``work_dir`` directory. Typical artifacts will
+All artifacts of this command are generated in the ``work_dir`` directory. Typically artifacts will
 include:
 
 ======================== =============================================================
@@ -177,7 +178,7 @@ Artifact                 Description
 ``Makefile.DUT*``        This is the Makefile generated by the DUT Plugin.
 ``Makefile.Reference*``  This is the Makefile generated by the Reference Plugin.
 ``report.html``          The final report generated at the end of the run after signature comparison.
-yaml files               Verified and checked YAML versions of the input ISA and platform YAMLs.
+  YAML files             Verified and checked YAML versions of the input ISA and Platform YAMLs.
 ``test_list.yaml``       This list of filtered tests from the ``database.yaml``.
-src directory            This will include a directory for each test in the ``test_list.yaml``. Each test-directory will include the test, compiled-binaries, signatures from both the DUT and the Reference Plugin.
-==================== =============================================================
+  src directory          This will include a directory for each test in the ``test_list.yaml``. Each test-directory will include the test, compiled-binaries, signatures from both the DUT and the Reference Plugin.
+======================== =============================================================

docs/source/database.rst

@@ -13,18 +13,18 @@ in them and constructs a dictionary of sorts, for the framework.
 The tests in the directory are identified by their relative path from the repository home.
 Each test in the database is defined as follows:
 
-* **file path**: the absolute path of the test on the said system
+* **file path**: the absolute path of the test on the said system:
 
-    * **commit_id**: Contains the recent commit id of the commit in which the test was modified.
+    * ``commit_id``: Contains the recent commit id of the commit in which the test was modified.
 
-    * **isa**: Contains the ISA required for the compilation of the test. This field is extracted from the *RVTEST_ISA* macro.
+    * ``isa``: Contains the ISA required for the compilation of the test. This field is extracted from the ``RVTEST_ISA`` macro.
 
-    * **parts**: Contains the individual parts present in the test and the conditions and macros required by each of them. The parts are identified by unique names as specified in the test. A test must contain at-least one part for it to be included in the database.
+    * ``parts``: Contains the individual parts present in the test and the conditions and macros required by each of them. The parts are identified by unique names as specified in the test. A test must contain at-least one part for it to be included in the database.
 
-        * **part name**: This node is extracted from the *RVTEST_CASE_START* macro in the test.
+        * **part name**: This node is extracted from the ``RVTEST_CASE_START`` macro in the test.
 
-            * **check**: A list of the check statements for the part as specified in the test. These translate to the conditions which need to be satisfied for this part to be included.
-            * **define**: A list of define statements for the part as specified in the test. These translate to the macros required by this part to run.
+            * ``check``: A list of the check statements for the part as specified in the test. These translate to the conditions which need to be satisfied for this part to be included.
+            * ``define``: A list of define statements for the part as specified in the test. These translate to the macros required by this part to run.
 
 Example:
 
@@ -52,18 +52,18 @@ Usage
 Reasons of Failure
 ^^^^^^^^^^^^^^^^^^
 
-Possible scenarios where database is not generated
+Possible scenarios where database is not generated:
 
   * There does not exist at-least one part in the test.
-  * Any part which has started does not end before another part starts or the code ends i.e. *RVTEST_CASE_START* exists for that part but *RVTEST_CASE_END* doesn't.
-  * The part names given in a *RVTEST_CASE_START*-*RVTEST_CASE_END* pair doesn't match.
-  * *RVTEST_ISA* macro isn't present in the test.
+  * Any part which has started does not end before another part starts or the code ends i.e. ``RVTEST_CASE_START`` exists for that part but ``RVTEST_CASE_END`` doesn't.
+  * The part names given in a ``RVTEST_CASE_START``-``RVTEST_CASE_END`` pair doesn't match.
+  * ``RVTEST_ISA`` macro isn't present in the test.
 
 Notes
 ^^^^^
 
-1. The database is always alphabetically ordered
+1. The database is always alphabetically ordered.
 2. The database checks for macro sanity - i.e. certain macros exists and in the correct order.
-3. Each time a new test is added to the ``suite`` directory, the database utility has to be run manually and the database.yaml
+3. Each time a new test is added to the ``suite`` directory, the database utility has to be run manually and the ``database.yaml``
    has to be up-streamed manually to the repository.
 

docs/source/inputs.rst

@@ -4,26 +4,26 @@
 Understanding RISCOF Inputs
 ###########################
 
-There are three major inputs that are required by most of the subcommand of RISCOF listed in the
+There are three major inputs that are required by most of the subcommand of ``riscof`` listed in the
 :ref:`commands` section:
 
-1. The ``config.ini`` file
-2. The ``DUT plugin directory``
-3. The ``Reference plugin directory``
+1. The ``config.ini`` file,
+2. The **DUT plugin directory**,
+3. The **Reference plugin directory**.
 
-This section will discuss each of the above requirements in detail
+This section will discuss each of the above requirements in detail.
 
 .. _config_syntax:
 
-Config.ini Syntax
-=================
+``config.ini`` syntax
+=====================
 
 The ``config.ini`` file follows the `ini <https://en.wikipedia.org/wiki/INI_file>`_ syntax and is 
 used to specify the name of the dut and reference plugins, path of the model plugins, plugin
-specific parameters and paths to the DUT's riscv-config based ISA and platform YAMLs.
+specific parameters and paths to the DUT's riscv-config based ISA and Platform YAMLs.
 
 
-A generic format of the ``config.ini`` file required by RISCOF is presented below. A similar
+A generic format of the ``config.ini`` file required by ``riscof`` is presented below. A similar
 template file can be generated using the ``--setup`` command of RISCOF.
 
 .. code-block:: ini
@@ -49,8 +49,8 @@ template file can be generated using the ``--setup`` command of RISCOF.
 
 The config file also allows you to define specific nodes/fields
 which can be used by the respective model plugins. For e.g., in the above template the
-`pluginpath` variable under the `[dut-name]` header is available to the DUT Python plugin file 
-via RISCOF. The plugin may use this pluginpath to detect the ``env`` files, scripts and other
+```pluginpath``` variable under the ``[dut-name]`` header is available to the DUT Python plugin file 
+via RISCOF. The plugin may use this ``pluginpath`` to detect the ``env`` files, scripts and other
 collaterals that may be required during execution.
 
 Similarly one can define more variables and prefixes here which can directly be
@@ -85,8 +85,8 @@ successful execution.
 
 A typical DUT plugin directory has the following structure::
 
- ├──dut-name/                    # DUT plugin templates
-    ├── env
+ ├── dut-name/                   # DUT plugin templates
+    ├── env/
     │   ├── link.ld              # DUT linker script
     │   └── model_test.h         # DUT specific header file
     ├── riscof_dut-name.py       # DUT Python plugin
@@ -95,8 +95,8 @@ A typical DUT plugin directory has the following structure::
 
 A typical Reference directory has the following structure::
 
- ├──ref-name/                    # Reference plugin templates
-    ├── env
+ ├── ref-name/                   # Reference plugin templates
+    ├── env/
     │   ├── link.ld              # Reference linker script
     │   └── model_test.h         # Reference specific header file
     ├── riscof_ref-name.py       # Reference Python plugin