From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id 8C75C432C7; Tue, 7 Nov 2023 15:40:03 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 0A58940698; Tue, 7 Nov 2023 15:40:03 +0100 (CET) Received: from foss.arm.com (foss.arm.com [217.140.110.172]) by mails.dpdk.org (Postfix) with ESMTP id E7C1D402A1 for ; Tue, 7 Nov 2023 15:40:00 +0100 (CET) Received: from usa-sjc-imap-foss1.foss.arm.com (unknown [10.121.207.14]) by usa-sjc-mx-foss1.foss.arm.com (Postfix) with ESMTP id 1187E13D5; Tue, 7 Nov 2023 06:40:45 -0800 (PST) Received: from [10.1.31.180] (e125442.arm.com [10.1.31.180]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPSA id 1560C3F703; Tue, 7 Nov 2023 06:39:58 -0800 (PST) Message-ID: <29607a15-4498-41c0-bc5e-2e6ae5628c4f@foss.arm.com> Date: Tue, 7 Nov 2023 14:39:56 +0000 MIME-Version: 1.0 User-Agent: Mozilla Thunderbird Subject: Re: [PATCH v5 03/23] dts: add basic developer docs Content-Language: en-US To: =?UTF-8?Q?Juraj_Linke=C5=A1?= , thomas@monjalon.net, Honnappa.Nagarahalli@arm.com, bruce.richardson@intel.com, jspewock@iol.unh.edu, probb@iol.unh.edu, paul.szczepanek@arm.com Cc: dev@dpdk.org References: <20230831100407.59865-1-juraj.linkes@pantheon.tech> <20231106171601.160749-1-juraj.linkes@pantheon.tech> <20231106171601.160749-4-juraj.linkes@pantheon.tech> From: Yoan Picchi In-Reply-To: <20231106171601.160749-4-juraj.linkes@pantheon.tech> Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 8bit X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org On 11/6/23 17:15, Juraj Linkeš wrote: > Expand the framework contribution guidelines and add how to document the > code with Python docstrings. > > Signed-off-by: Juraj Linkeš > --- > 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..b1e99107c3 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 ` 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 `_. > +See an example of the style > +`here `_. > +For cases which are not covered by the Google style, refer > +to `PEP 257 `_. 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 `_. > + * 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. Not your change, but it does highlight a previous mistake : "they're is" > > +#. **Configuration, traffic and other logic** > + > + The ``TestSuite`` class contains a variety of methods for anything that > + a test suite setup or teardown or a test case may need to do. Three way or. There's a need for an oxford coma: setup, teardown, or a test case > + > + 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 > ------------------- >