Re: [PATCH] dts: improve documentation

[Thomas Monjalon <thomas@monjalon.net>]

03/01/2024 13:54, Luca Vizzarro:
> Improve instructions for installing dependencies, configuring and
> launching the project. Finally, document the configuration schema
> by adding more comments to the example and documenting every
> property and definition.

Thank you for taking care of the documentation.

> +Luca Vizzarro <Luca.Vizzarro@arm.com>

For consistency, we don't use uppercase characters in email addresses.


> -      poetry install
> +      poetry install --no-root

Please could you explain this change in the commit log?


>  DTS needs to know which nodes to connect to and what hardware to use on those nodes.
> -Once that's configured, DTS needs a DPDK tarball and it's ready to run.
> +Once that's configured, DTS needs a DPDK tarball or a git ref ID and it's ready to run.

That's assuming DTS is compiling DPDK.
We may want to provide an already compiled DPDK to DTS.


> -   usage: main.py [-h] [--config-file CONFIG_FILE] [--output-dir OUTPUT_DIR] [-t TIMEOUT]
> -                  [-v VERBOSE] [-s SKIP_SETUP] [--tarball TARBALL]
> -                  [--compile-timeout COMPILE_TIMEOUT] [--test-cases TEST_CASES]
> -                  [--re-run RE_RUN]
> +   (dts-py3.10) $ ./main.py --help

Why adding this line?
Should we remove the shell prefix referring to a specific Python version?

> +   usage: main.py [-h] [--config-file CONFIG_FILE] [--output-dir OUTPUT_DIR] [-t TIMEOUT] [-v VERBOSE]
> +                  [-s SKIP_SETUP] [--tarball TARBALL] [--compile-timeout COMPILE_TIMEOUT]
> +                  [--test-cases TEST_CASES] [--re-run RE_RUN]
>  
> -   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.

In general it is better to avoid long lines, and split after a punctation.
I think we should take the habit to always go to the next line after the end of a sentence.


> -                           [DTS_OUTPUT_DIR] Output directory where dts logs and results are
> -                           saved. (default: output)
> +                           [DTS_OUTPUT_DIR] Output directory where dts logs and results are saved.

dts -> DTS


> +Configuration Schema
> +--------------------
> +
> +Definitions
> +~~~~~~~~~~~
> +
> +_`Node name`
> +   *string* – A unique identifier for a node. **Examples**: ``SUT1``, ``TG1``.
> +
> +_`ARCH`
> +   *string* – The CPU architecture. **Supported values**: ``x86_64``, ``arm64``, ``ppc64le``.
> +
> +_`CPU`
> +   *string* – The CPU microarchitecture. Use ``native`` for x86. **Supported values**: ``native``, ``armv8a``, ``dpaa2``, ``thunderx``, ``xgene1``.
> +
> +_`OS`
> +   *string* – The operating system. **Supported values**: ``linux``.
> +
> +_`Compiler`
> +   *string* – The compiler used for building DPDK. **Supported values**: ``gcc``, ``clang``, ``icc``, ``mscv``.
> +
> +_`Build target`
> +   *object* – Build targets supported by DTS for building DPDK, described as:
> +
> +   ==================== =========================================================================================
> +   ``arch``             See `ARCH`_
> +   ``os``               See `OS`_
> +   ``cpu``              See `CPU`_
> +   ``compiler``         See `Compiler`_
> +   ``compiler_wrapper`` *string* – Value prepended to the CC variable for the DPDK build.

Please don't add compilation configuration for now,
I would like to work on the schema first.
This is mostly imported from the old DTS and needs to be rethink.