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 7FFF8432D3; Wed, 8 Nov 2023 10:01:47 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id F2DFB42DDA; Wed, 8 Nov 2023 10:01:46 +0100 (CET) Received: from mail-ed1-f47.google.com (mail-ed1-f47.google.com [209.85.208.47]) by mails.dpdk.org (Postfix) with ESMTP id 6FCB942DD8 for ; Wed, 8 Nov 2023 10:01:45 +0100 (CET) Received: by mail-ed1-f47.google.com with SMTP id 4fb4d7f45d1cf-53e2308198eso11083784a12.1 for ; Wed, 08 Nov 2023 01:01:45 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=pantheon.tech; s=google; t=1699434105; x=1700038905; darn=dpdk.org; h=content-transfer-encoding:cc:to:subject:message-id:date:from :in-reply-to:references:mime-version:from:to:cc:subject:date :message-id:reply-to; bh=eALm/8mhoETWKusH0iAbtsyjfjyH+/U1jtIttOFsNU8=; b=jcOIoXd+yH21/dfzfoVWrDKaX3pu+jsLcvhbZXo/+ojsAOfA6tV5ySFWHbpKlcmbph +bOAlM81oj66UhGrSQGHTo68NgGlwfdXhcDW1jhnN+cdjne2Klje8AxSYo/5Nq+oyDfs IzK+HIHpGDc5ysEjcpUe/xh8Kuuquv55YBwD9SGKISzp2gvoKJ+3SZSg+hsWRaKXkb7U 7PnK/qAjoLZHQuWypDUATdQROqPQ8QXs6xrc440Kh+7AGPBw8tOV5/8iF5b5EKAGvjxL N93GWsDhEaPaQOUTy/Aalzi+kxfaBDCSrsP8CanBbGAdEzTgqVvBfB+1kybPtqYSwcny STpw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1699434105; x=1700038905; h=content-transfer-encoding:cc:to:subject:message-id:date:from :in-reply-to:references:mime-version:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=eALm/8mhoETWKusH0iAbtsyjfjyH+/U1jtIttOFsNU8=; b=DE/YkIMzItxeZSLrsMGpjkvJ02nvVriEvT+emGWOJ8ILFPx4uR8xy+vmxPO0io2hvt C0fdEIAR9Xj3F7ciuL3fmX7II26Kckoz1KcJvUmA7G25CVVB56Pg9C7FaCydwSKloYz0 3gmQOFCWW9Ilt8IL3aAqAK9HJF4l3YAW0UB5T7Ti809Nhd/tkfIYAmBq/8luM6bHUFyV 0wSio2slIZtH8sFmcVbPiUimltjkmybIpoBwKABOccKpNzZwZh8x11IOK0dJ1LGIlmht kmwic9QFME+I5TgBYZefvcHx7xXDcvoAl4lfmgGF/WOTHToon/NMWq1xwFLGHbWP3fN0 YZgA== X-Gm-Message-State: AOJu0Yxaf6yQ703M9pFUQ78flKahhOF2t6Bq1FOO82Fza2NRMNy2MVrS /Vx4koabIqSvf2lMakIel1r1J+Xj+Oo7AaOH7e/wpQ== X-Google-Smtp-Source: AGHT+IHv23+f5KLSPKl+DU2G6WXSbXutXuwrKU8dbNKgxLQna3nozWc9ZXLJ8FhrRhvsVlPhx1HFVdNR9D3ueX8KF6g= X-Received: by 2002:a50:c351:0:b0:543:4ff0:4fd5 with SMTP id q17-20020a50c351000000b005434ff04fd5mr788338edb.39.1699434104980; Wed, 08 Nov 2023 01:01:44 -0800 (PST) MIME-Version: 1.0 References: <20230831100407.59865-1-juraj.linkes@pantheon.tech> <20231106171601.160749-1-juraj.linkes@pantheon.tech> <20231106171601.160749-4-juraj.linkes@pantheon.tech> <29607a15-4498-41c0-bc5e-2e6ae5628c4f@foss.arm.com> In-Reply-To: <29607a15-4498-41c0-bc5e-2e6ae5628c4f@foss.arm.com> From: =?UTF-8?Q?Juraj_Linke=C5=A1?= Date: Wed, 8 Nov 2023 10:01:33 +0100 Message-ID: Subject: Re: [PATCH v5 03/23] dts: add basic developer docs To: Yoan Picchi Cc: thomas@monjalon.net, Honnappa.Nagarahalli@arm.com, bruce.richardson@intel.com, jspewock@iol.unh.edu, probb@iol.unh.edu, paul.szczepanek@arm.com, dev@dpdk.org Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable 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 Tue, Nov 7, 2023 at 3:40=E2=80=AFPM Yoan Picchi wrote: > > On 11/6/23 17:15, Juraj Linke=C5=A1 wrote: > > Expand the framework contribution guidelines and add how to document th= e > > code with Python docstrings. > > > > Signed-off-by: Juraj Linke=C5=A1 > > --- > > 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 su= ites. > > + > > +The framework contains the logic needed to run test cases, such as con= necting to nodes, > > +running DPDK apps and collecting results. > > + > > +The test cases call APIs from the framework to test their scenarios. A= dding 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 th= e 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 c= onform 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 case= s which are not covered by > > +the two style guides, where we deviate or where some additional clarif= ication 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 docstri= ng 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 a= lso be recorded > > + in the ``Attributes:`` section. > > + * Class variables/attributes, on the other hand, should be document= ed with ``#:`` above > > + the type annotated line. The description may be omitted if the me= aning 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 doc= s contain the assigned value. > > + * When referencing a parameter of a function or a method in their d= ocstring, don't use > > + any articles and put the parameter into single backticks. This mi= mics 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 te= st suite: > > | These methods don't need to be implemented if there's no need fo= r 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" > Good catch - we'll be adding to this guide in the future so we can fix it t= hen. > > > > +#. **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 > Thanks, I'll change this. > > + > > + 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 sui= tes. If there's any > > + functionality or logic missing from the framework, it should be imp= lemented 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 tes= t suite: > > and used by the test suite via the ``sut_node`` field. > > > > > > +.. _dts_dev_tools: > > + > > DTS Developer Tools > > ------------------- > > >