Comments about the Documentation

[Harald Seiler]

Hello Daniel,

thanks a lot for the feedback!

On Thu, 2020-03-05 at 13:11 +0000, daniel garcia wrote:
> Quick start
> 
> In the part that says “--interactive” the example uses “tbot
> selftest_uname -vi” i assume that the “i” represent “--interactive”
> but this assumption is based on experience. It could be inserted in an
> explicit way.
> 
> Testcases
> 
> It could be mentioned how to set a “workspace” to develop “tbot
> testcases” How “tbot -t my_most_amazing.py hell_world” works?

Yes.  I want to add a step-by-step guide on how one could build a setup
for tbot.  This includes both the hardware side (remote power, serial
console, network) and also the software side (directory layout of the
workspace, config files, testcases).

> what does the “-t” do? (solution: it is a parameter that tbot receives
> to explicit give the path of where is the “my_most_amazing.py”) what
> does hello_world represent? (solution: it represents the name of the
> testcase (function) in the “my_most_amazing.py” file (it could be
> explicit)) why should i name the file “tc.py”?  does tbot
> automatically detect where is “tc.py” file in my workspace?
 
This is actually documented in the man-page [0] but unfortunately it is
not part of the online docs.  I'll have to take another look how to
integrate that ...

[0]: https://github.com/Rahix/tbot/blob/master/Documentation/tbot.1
 
> Configuration In the python classes presented, which are all the
> reserved variables (propiedades) that i can use?  what is the function
> “def workdir(self):” for?  what is the parameter “-l” for?  is there
> some way to connect to a lab-host with the password?

This is usually documented for each class you inherit from.  So for
example, the ParamikoConnector [1] documents all possible properties for
the lab-host connection.

But maybe it makes sense to create an index of all those properties,
their meaning and what classes need to be inherited from for them to be
available.

[1]: https://tbot.tools/modules/machine_connector.html?highlight=paramiko#tbot.machine.connector.ParamikoConnector

> Hardware interaction what is the name of the file that the example
> uses?
> 
> Configuration
> 
> Board Config Board-Hardware Config How does the “self.host. ……..”
> works? if it is called from the board config. (it is explained in
> commentaries that are in the example code).

This is actually a bit intransparent and I would like to change it at
some point.  `self.host` is set by the ConsoleConnector [2] at the
moment so it is only available if the `ConsoleConnector` was used.  It
would be nice to A) document this and B) make this mechanism somehow
more transparent and maybe always have the host available (when
applicable).

[2]: https://tbot.tools/modules/machine_connector.html?highlight=paramiko#tbot.machine.connector.ConsoleConnector

> U-Boot Config
> 
> Suggestion: Put the name of the files that are used for the examples.

Makes sense!

> In the example is missing “import tbot” The class “MyBoardUboot” must
> be in the same file of the Board configuration (suggestion: mention it
> in a explicit way) SUggestion: mention that you must specify the
> “prompt” that the uboot in the “board” is using since it can cause
> problems if the “prompt” property is not the same as the prompt of the
> board.

+1

> Linux (from U-boot) Config
> 
> Suggestion: put an example of how you can run the “BeagleBoneLinux”
> example.  Suggestion: mention that the example must be in  the file
> with the U-boot configuration for the board.

+1

> 
> Logging
> 
> Suggestion: put some examples about how to use “logs”.  Suggestion:
> put some examples about how can i use “generators/logparser.py”

Or actually move the logparser into the tbot module somewhere and
document it properly.  I've been thinking about integrating the
generators more tightly with the rest of tbot but haven't come around
to doing so yet :/

> Generators Put some examples about how to use those generators.

+1

> 
> 
> -------------------------------------------------------------------------------
> 
> Hi, can in work in the patches of the documentation?
> if so, should i send the patches via email or via pull request?

Definitely!  Patches via ML or via GitHub are both welcome.

> 
> thanks.
> 

-- 
Harald