[PATCH v2 6/7] doc: update argument options for external DPDK build

[Luca Vizzarro <luca.vizzarro@arm.com>]

From: Tomáš Ďurovec <tomas.durovec@pantheon.tech>

By adding support for external build, we extend the
argument documentation for supported options.

Signed-off-by: Tomáš Ďurovec <tomas.durovec@pantheon.tech>
Signed-off-by: Luca Vizzarro <luca.vizzarro@arm.com>
---
 doc/guides/tools/dts.rst | 75 ++++++++++++++++++++++++----------------
 1 file changed, 45 insertions(+), 30 deletions(-)

diff --git a/doc/guides/tools/dts.rst b/doc/guides/tools/dts.rst
index 65cce9e5ed..7b90c4856e 100644
--- a/doc/guides/tools/dts.rst
+++ b/doc/guides/tools/dts.rst
@@ -195,10 +195,10 @@ Running DTS
 -----------
 
 DTS needs to know which nodes to connect to and what hardware to use on those nodes.
-Once that's configured, either a DPDK source code tarball or a Git revision ID
-of choice needs to be supplied.
-DTS will use this to compile DPDK on the SUT node
-and then run the tests with the newly built binaries.
+Once that's configured, either a DPDK source code tarball or tree folder need to be supplied whether
+these are on your DTS host machine or the SUT node.
+DTS can accept a pre-compiled build placed in a subdirectory, or it will compile DPDK on the SUT
+node, and then run the tests with the newly built binaries.
 
 
 Configuring DTS
@@ -221,44 +221,59 @@ DTS is run with ``main.py`` located in the ``dts`` directory after entering Poet
 .. code-block:: console
 
    (dts-py3.10) $ ./main.py --help
-   usage: main.py [-h] [--config-file FILE_PATH] [--output-dir DIR_PATH] [-t SECONDS] [-v] [-s] (--tarball FILE_PATH | --revision ID)
-                  [--compile-timeout SECONDS] [--test-suite TEST_SUITE [TEST_CASES ...]] [--re-run N_TIMES]
+   usage: main.py [-h] [--config-file FILE_PATH] [--output-dir DIR_PATH] [-t SECONDS] [-v] [--dpdk-tree DIR_PATH | --tarball FILE_PATH] [--remote-source]
+                  [--precompiled-build-dir DIR_NAME] [--compile-timeout SECONDS] [--test-suite TEST_SUITE [TEST_CASES ...]] [--re-run N_TIMES]
+                  [--random-seed NUMBER]
 
-   Run DPDK test suites. All options may be specified with the environment variables provided in brackets. Command line arguments have higher
-   priority.
+   Run DPDK test suites. All options may be specified with the environment variables provided in brackets. Command line arguments have higher priority.
 
    options:
-     -h, --help            show this help message and exit
-     --config-file FILE_PATH
-                           [DTS_CFG_FILE] The configuration file that describes the test cases, SUTs and targets. (default: conf.yaml)
-     --output-dir DIR_PATH, --output DIR_PATH
+   -h, --help            show this help message and exit
+   --config-file FILE_PATH
+                           [DTS_CFG_FILE] The configuration file that describes the test cases, SUTs and DPDK build configs. (default:
+                           /home/lucviz01/dpdk/dts/conf.yaml)
+   --output-dir DIR_PATH, --output DIR_PATH
                            [DTS_OUTPUT_DIR] Output directory where DTS logs and results are saved. (default: output)
-     -t SECONDS, --timeout SECONDS
+   -t SECONDS, --timeout SECONDS
                            [DTS_TIMEOUT] The default timeout for all DTS operations except for compiling DPDK. (default: 15)
-     -v, --verbose         [DTS_VERBOSE] Specify to enable verbose output, logging all messages to the console. (default: False)
-     -s, --skip-setup      [DTS_SKIP_SETUP] Specify to skip all setup steps on SUT and TG nodes. (default: False)
-     --tarball FILE_PATH, --snapshot FILE_PATH
-                           [DTS_DPDK_TARBALL] Path to DPDK source code tarball to test. (default: None)
-     --revision ID, --rev ID, --git-ref ID
+   -v, --verbose           [DTS_VERBOSE] Specify to enable verbose output, logging all messages to the console. (default: False)
+   --revision ID, --rev ID, --git-ref ID
                            [DTS_DPDK_REVISION_ID] Git revision ID to test. Could be commit, tag, tree ID etc. To test local changes, first
                            commit them, then use their commit ID. (default: None)
-     --compile-timeout SECONDS
+   --compile-timeout SECONDS
                            [DTS_COMPILE_TIMEOUT] The timeout for compiling DPDK. (default: 1200)
-     --test-suite TEST_SUITE [TEST_CASES ...]
-                           [DTS_TEST_SUITES] A list containing a test suite with test cases. The first parameter is the test suite name, and
-                           the rest are test case names, which are optional. May be specified multiple times. To specify multiple test suites
-                           in the environment variable, join the lists with a comma. Examples: --test-suite suite case case --test-suite
-                           suite case ... | DTS_TEST_SUITES='suite case case, suite case, ...' | --test-suite suite --test-suite suite case
-                           ... | DTS_TEST_SUITES='suite, suite case, ...' (default: [])
-     --re-run N_TIMES, --re_run N_TIMES
+   --test-suite TEST_SUITE [TEST_CASES ...]
+                           [DTS_TEST_SUITES] A list containing a test suite with test cases. The first parameter is the test suite name, and the rest are
+                           test case names, which are optional. May be specified multiple times. To specify multiple test suites in the environment
+                           variable, join the lists with a comma. Examples: --test-suite suite case case --test-suite suite case ... |
+                           DTS_TEST_SUITES='suite case case, suite case, ...' | --test-suite suite --test-suite suite case ... | DTS_TEST_SUITES='suite,
+                           suite case, ...' (default: [])
+   --re-run N_TIMES, --re_run N_TIMES
                            [DTS_RERUN] Re-run each test case the specified number of times if a test failure occurs. (default: 0)
-     --random-seed NUMBER  [DTS_RANDOM_SEED] The seed to use with the pseudo-random generator. If not specified, the configuration value is
-                           used instead. If that's also not specified, a random seed is generated. (default: None)
+   --random-seed NUMBER  [DTS_RANDOM_SEED] The seed to use with the pseudo-random generator. If not specified, the configuration value is used instead.
+                           If that's also not specified, a random seed is generated. (default: None)
+
+   DPDK Build Options:
+   Arguments in this group (and subgroup) will be applied to a DPDKLocation when the DPDK tree, tarball or revision will be provided, other arguments
+   like remote source and build dir are optional. A DPDKLocation from settings are used instead of from config if construct successful.
+
+   --dpdk-tree DIR_PATH  [DTS_DPDK_TREE] The path to the DPDK source tree directory to test. Cannot be used in conjunction with --tarball. (default:
+                           None)
+   --tarball FILE_PATH, --snapshot FILE_PATH
+                           [DTS_DPDK_TARBALL] The path to the DPDK source tarball to test. DPDK must be contained in a folder with the same name as the
+                           tarball file. Cannot be used in conjunction with --dpdk-tree. (default: None)
+   --remote-source       [DTS_REMOTE_SOURCE] Set this option if either the DPDK source tree or tarball to be used are located on the SUT node. Can only
+                           be used with --dpdk-tree or --tarball. (default: False)
+   --precompiled-build-dir DIR_NAME
+                           [DTS_PRECOMPILED_BUILD_DIR] Define the subdirectory under the DPDK tree root directory where the pre-compiled binaries are
+                           located. If set, DTS will build DPDK under the `build` directory instead. Can only be used with --dpdk-tree or --tarball.
+                           (default: None)
 
 
 The brackets contain the names of environment variables that set the same thing.
-The minimum DTS needs is a config file and a DPDK tarball or git ref ID.
-You may pass those to DTS using the command line arguments or use the default paths.
+The minimum DTS needs is a config file and a pre-built DPDK or DPDK
+sources location which can be specified in said config file or on the
+command line or environment variables.
 
 Example command for running DTS with the template configuration and DPDK tag v23.11:
 
-- 
2.43.0