[LTP] [PATCH] doc: Add basic shell test description

[Cyril Hrubis]

> > +Shell API overview
> > +------------------
> > +
> > +First lines of the shell test should be a shebang, a license, and copyrights.
> > +
> > +.. code-block:: shell
> > +
> > +   #!/bin/sh
> > +   # SPDX-License-Identifier: GPL-2.0-or-later
> > +   # Copyright 2099 Foo Bar <foo.bar@email.com>
> > +
> > +A documentation comment block formatted in ReStructuredText should follow right
> > +after these lines. This comment is parsed and exported into the LTP
> > +documentation at https://linux-test-project.readthedocs.io/en/latest/users/test_catalog.html
> 
> +1. Great, I did not realize it's ok to use at least #doc part for normal shell
> tests (i.e. these without shell loader).

That should indeed work fine. You can have a doc block in old shell test
and it would be picked up by the metadata parser.

> > +
> > +.. code-block:: shell
> > +
> > +   # ---
> > +   # doc
> > +   # Test for a foo bar.
> > +   #
> > +   # This test is testing foo by checking that bar is doing xyz.
> > +   # ---
> > +
> 
> I would frankly link the old API doc (and link :master:`testcases/lib/tst_test.sh`)...
> https://github.com/linux-test-project/ltp/blob/master/doc/old/Shell-Test-API.asciidoc
> 
> > +The shell loader test library uses the C test library internally by parsing a
> > +special JSON formatted comment and initializing it accordingly. The JSON format
> > +is nearly 1:1 serialization of the C tst_test structure into a JSON. The
> > +environment must be always preset even when it's empty.
> 
> And here would have subtitle "shell loader test library".  Why? It'd be good to
> admit we have plain shell (which uses tst_test.sh) and shell loader. Of course,
> shell loader could be a mentioned first, then old API:

Generally I would like to avoid mixing documentation for different APIs.
I'm afraid that would make things unnecessarily confusing.

-- 
Cyril Hrubis
chrubis@suse.cz