On Tue, Nov 7, 2023 at 3:40 PM Yoan Picchi <yoan.pic...@foss.arm.com> wrote: > > 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š <juraj.lin...@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..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 > > <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. > > 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 then. > > > > +#. **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 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 > > ------------------- > > >
