From mboxrd@z Thu Jan 1 00:00:00 1970
Return-Path: <dev-bounces@dpdk.org>
Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124])
by inbox.dpdk.org (Postfix) with ESMTP id 651F343339;
Wed, 15 Nov 2023 14:11:59 +0100 (CET)
Received: from mails.dpdk.org (localhost [127.0.0.1])
by mails.dpdk.org (Postfix) with ESMTP id 388BC40A7A;
Wed, 15 Nov 2023 14:11:58 +0100 (CET)
Received: from mail-ed1-f42.google.com (mail-ed1-f42.google.com
[209.85.208.42]) by mails.dpdk.org (Postfix) with ESMTP id 29F0340A6E
for <dev@dpdk.org>; Wed, 15 Nov 2023 14:11:54 +0100 (CET)
Received: by mail-ed1-f42.google.com with SMTP id
4fb4d7f45d1cf-53dd3f169d8so10145359a12.3
for <dev@dpdk.org>; Wed, 15 Nov 2023 05:11:54 -0800 (PST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
d=pantheon.tech; s=google; t=1700053914; x=1700658714; darn=dpdk.org;
h=content-transfer-encoding:mime-version:references:in-reply-to
:message-id:date:subject:cc:to:from:from:to:cc:subject:date
:message-id:reply-to;
bh=ZYiXW2Z88ESYnyFNqmTUgTLHumo8eKturZmLII8hMZI=;
b=aXku2v9p486K31hn6J8mzDzvKuoCaBnhPh9pGS4SRel+U0hae9AcAg+74oy26k/VKI
AxisP4NzK/SUccvjZMJ6bowMl3Oa3Ggn1/Rjzx91VPWsPMbtJbpcarWlDofA/unQFeCI
GRUYUxrZ2RBHto3YhpbHjBPUHoR5cPrrINuCpC7kpWu8suKQ8QLKDtqUXPLhTxPsOY9H
iqGDsKRF92PUrNmFsL0gZO6EpUHcvGCHvnFZ1LCMOqbfnL4ECkD2LqD0dHxxv6kkdYh5
RZr036/J85UjaaCxn3bEL0wqHSg5UTszNZLSJ/KfF0B2F9csf4qLNvmh3CKDh2lFBLFR
cSYg==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
d=1e100.net; s=20230601; t=1700053914; x=1700658714;
h=content-transfer-encoding:mime-version:references:in-reply-to
:message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc
:subject:date:message-id:reply-to;
bh=ZYiXW2Z88ESYnyFNqmTUgTLHumo8eKturZmLII8hMZI=;
b=rY07RU84bGEJDytztVac4DBphx/FUd4WjOs+CKaKjUib6v5+w2bLFR+w1gqA5/ITas
P4AzmDQbc37nsiHhtPnXu72BxpwA8PRvpXJn7Ym/HLxaNklzW8/BRQAShi1rUjY4PbsW
3zXgwdiM4fGe6xzOuBc7ga2yo4KHp/TR+syx3LpRk9y4rfonUyCypPpSEONiDDjeb3Kl
H5NKYJ3snYlNMYafP52nSVn0r8dGVbLuqXP6DQGnjMv3Xk7fZbel+7PaYf0Uq0zu2wXN
n7FGpsQmfoqE7Rb9uLajnaOxdWovdt/IYH8eq63GToIMpv0Iqx7t32SsNwLuiY71yJHj
R0zQ==
X-Gm-Message-State: AOJu0YwXt4nNlcgY84GPcYfXgj8f/EG3M1Yq07oM6NEaKgIngM2DZ4oE
gFZLae8pvGxlj6IP7rgkR/nNyA==
X-Google-Smtp-Source: AGHT+IG61Q9nwDKc1AdvPqoWCKviySVGivXbaGKJnUmfSPmmCsivVj3hGvPptgJ2yt0s6i2XJ+CYYQ==
X-Received: by 2002:a17:906:1147:b0:9da:f372:4f6c with SMTP id
i7-20020a170906114700b009daf3724f6cmr8005614eja.32.1700053913821;
Wed, 15 Nov 2023 05:11:53 -0800 (PST)
Received: from jlinkes-PT-Latitude-5530.pantheon.local
(81.89.53.154.host.vnet.sk. [81.89.53.154])
by smtp.gmail.com with ESMTPSA id
tb16-20020a1709078b9000b009f2b7282387sm1011914ejc.46.2023.11.15.05.11.53
(version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);
Wed, 15 Nov 2023 05:11:53 -0800 (PST)
From: =?UTF-8?q?Juraj=20Linke=C5=A1?= <juraj.linkes@pantheon.tech>
To: thomas@monjalon.net, Honnappa.Nagarahalli@arm.com, jspewock@iol.unh.edu,
probb@iol.unh.edu, paul.szczepanek@arm.com, yoan.picchi@foss.arm.com
Cc: dev@dpdk.org, =?UTF-8?q?Juraj=20Linke=C5=A1?= <juraj.linkes@pantheon.tech>
Subject: [PATCH v7 03/21] dts: add basic developer docs
Date: Wed, 15 Nov 2023 14:09:41 +0100
Message-Id: <20231115130959.39420-4-juraj.linkes@pantheon.tech>
X-Mailer: git-send-email 2.34.1
In-Reply-To: <20231115130959.39420-1-juraj.linkes@pantheon.tech>
References: <20231108125324.191005-23-juraj.linkes@pantheon.tech>
<20231115130959.39420-1-juraj.linkes@pantheon.tech>
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
X-BeenThere: dev@dpdk.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: DPDK patches and discussions <dev.dpdk.org>
List-Unsubscribe: <https://mails.dpdk.org/options/dev>,
<mailto:dev-request@dpdk.org?subject=unsubscribe>
List-Archive: <http://mails.dpdk.org/archives/dev/>
List-Post: <mailto:dev@dpdk.org>
List-Help: <mailto:dev-request@dpdk.org?subject=help>
List-Subscribe: <https://mails.dpdk.org/listinfo/dev>,
<mailto:dev-request@dpdk.org?subject=subscribe>
Errors-To: dev-bounces@dpdk.org
Expand the framework contribution guidelines and add how to document the
code with Python docstrings.
Signed-off-by: Juraj Linkeš <juraj.linkes@pantheon.tech>
---
doc/guides/tools/dts.rst | 73 ++++++++++++++++++++++++++++++++++++++++
1 file changed, 73 insertions(+)
diff --git a/doc/guides/tools/dts.rst b/doc/guides/tools/dts.rst
index 32c18ee472..cd771a428c 100644
--- a/doc/guides/tools/dts.rst
+++ b/doc/guides/tools/dts.rst
@@ -264,6 +264,65 @@ which be changed with the ``--output-dir`` command line argument.
The results contain basic statistics of passed/failed test cases and DPDK version.
+Contributing to DTS
+-------------------
+
+There are two areas of contribution: The DTS framework and DTS test suites.
+
+The framework contains the logic needed to run test cases, such as connecting to nodes,
+running DPDK apps and collecting results.
+
+The test cases call APIs from the framework to test their scenarios. Adding test cases may
+require adding code to the framework as well.
+
+
+Framework Coding Guidelines
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When adding code to the DTS framework, pay attention to the rest of the code
+and try not to divert much from it. The :ref:`DTS developer tools <dts_dev_tools>` will issue
+warnings when some of the basics are not met.
+
+The code must be properly documented with docstrings. The style must conform to
+the `Google style <https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings>`_.
+See an example of the style
+`here <https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html>`_.
+For cases which are not covered by the Google style, refer
+to `PEP 257 <https://peps.python.org/pep-0257/>`_. There are some cases which are not covered by
+the two style guides, where we deviate or where some additional clarification is helpful:
+
+ * The __init__() methods of classes are documented separately from the docstring of the class
+ itself.
+ * The docstrigs of implemented abstract methods should refer to the superclass's definition
+ if there's no deviation.
+ * Instance variables/attributes should be documented in the docstring of the class
+ in the ``Attributes:`` section.
+ * The dataclass.dataclass decorator changes how the attributes are processed. The dataclass
+ attributes which result in instance variables/attributes should also be recorded
+ in the ``Attributes:`` section.
+ * Class variables/attributes, on the other hand, should be documented with ``#:`` above
+ the type annotated line. The description may be omitted if the meaning is obvious.
+ * The Enum and TypedDict also process the attributes in particular ways and should be documented
+ with ``#:`` as well. This is mainly so that the autogenerated docs contain the assigned value.
+ * When referencing a parameter of a function or a method in their docstring, don't use
+ any articles and put the parameter into single backticks. This mimics the style of
+ `Python's documentation <https://docs.python.org/3/index.html>`_.
+ * When specifying a value, use double backticks::
+
+ def foo(greet: bool) -> None:
+ """Demonstration of single and double backticks.
+
+ `greet` controls whether ``Hello World`` is printed.
+
+ Args:
+ greet: Whether to print the ``Hello World`` message.
+ """
+ if greet:
+ print(f"Hello World")
+
+ * The docstring maximum line length is the same as the code maximum line length.
+
+
How To Write a Test Suite
-------------------------
@@ -293,6 +352,18 @@ There are four types of methods that comprise a test suite:
| These methods don't need to be implemented if there's no need for them in a test suite.
In that case, nothing will happen when they're is executed.
+#. **Configuration, traffic and other logic**
+
+ The ``TestSuite`` class contains a variety of methods for anything that
+ a test suite setup, a teardown, or a test case may need to do.
+
+ The test suites also frequently use a DPDK app, such as testpmd, in interactive mode
+ and use the interactive shell instances directly.
+
+ These are the two main ways to call the framework logic in test suites. If there's any
+ functionality or logic missing from the framework, it should be implemented so that
+ the test suites can use one of these two ways.
+
#. **Test case verification**
Test case verification should be done with the ``verify`` method, which records the result.
@@ -308,6 +379,8 @@ There are four types of methods that comprise a test suite:
and used by the test suite via the ``sut_node`` field.
+.. _dts_dev_tools:
+
DTS Developer Tools
-------------------
--
2.34.1