Re: Documentation and Docstring Format

[Lucas Meneghel Rodrigues]

On 04/17/2014 12:09 PM, Tim Flink wrote:

On Thu, 17 Apr 2014 10:03:24 -0400 (EDT)
Kamil Paral  wrote:


https://pythonhosted.org/an_example_pypi_project/sphinx.html#auto-directives


I'm not suggesting that we drop everything and fix all the
docstrings right now but I am suggesting that we start following
the sphinx docstring format for new code and fix other-formatted
docstrings as we come across them.

Any objections?


Well, my only objection is, that the Sphinx format has IMHO the
worst impact on how docstrings look.


That is my impression as well [1]. The improved versions of Markdown
are more legible and easier to remember than ReST (+Sphinx) [2].
OTOH, there are certain Sphinx features that look really great (for
example documentation of attributes or global variables). So let's
try it.


This gets down to personal preference but in general, I prefer ReST to
markdown.

I thought that we had already decided to use sphinx when mike did his
documentation tool survey a couple of months ago.


Maybe it is just me, but I use help() more often than html docs.


The Spyder editor shows HTML output of docstrings, even though it
seems it uses plain ReST conversion instead of Sphinx conversion.



But other than that, I have no issues.


I played with it a little and the syntax is quite complex. If we are
to use it, we will need at least:
1. basic sphinx config committed into the repository
2. some instructions in the readme how to generate the docs


Yeah, my plan is to have sphinx docs live in the same repo as
libtaskotron so changes can be built locally before submitting any
patches.

"build docs" sounds like a reasonable section to have in the dev
documentation.


so that we can at least generate the docs locally and look at it
before posting the patch. As Tim already said, sphinx is pretty
strict in its syntax.

There is one more alternative, I think - use Sphinx for docs
generation, but keep the docstrings free-form (I assume there must be
an option in Sphinx to do that). That way we lose some pretty
formatting, but won't be forced to adhere to a particular syntax.


I put an example of the output from both sphinx-style docstrings and
freeform docstrings up on fedorapeople:

http://tflink.fedorapeople.org/taskotron/test-libtaskotron-docs/library.html

It sounds like the general consensus is that sphinx-style docstrings
are ugly but generate nice html output and it's not clear whether the
ugly-ness of the docstrings is worth the nice html api docs.


My 2 cents: The sphinx docstrings are not that bad, and the HTML output 
in places like readthedocs.org is quite good. Besides, a good deal of 
python projects fully embrace sphinx, precisely the reason why we 
migrated all autotest, virt-test and related projects docstrings. 
Example straight from virt-test:


http://virt-test.readthedocs.org/en/latest/api/modules.html

From avocado:

http://avocado-framework.readthedocs.org/en/latest/api/modules.html

Besides, rst is a quite capable language to write great non API 
documentation and keep it in tree, using sphinx as well. So with one 
solution, you get it all. Another reason why having not-so-pretty 
docstrings in this case is worth the effort.

___
qa-devel mailing list
qa-de...@lists.fedoraproject.org
https://admin.fedoraproject.org/mailman/listinfo/qa-devel

Re: Taskbot: TAP vs Subunit

[Lucas Meneghel Rodrigues]

On 10/31/2013 02:27 PM, Josef Skladanka wrote:

Lucas,

do you use any library for producing TAP format?


No, at least not in the sense of an external project. Producing TAP in 
the client is an autotest specific implementation. It is the TAPReport() 
object defined in:


https://github.com/autotest/autotest/blob/master/client/shared/base_job.py#L682


Also, do you have any TAP parser, or do you just emit it?


Currently, autotest only outputs TAP, there's no parser available.

Cleber from my time was evaluating writing one, but we didn't go forward 
with it.


Matěj Cepl, also a Red Hat employee, implemented one parser at some 
point, but I think he felt discouraged because people did not give 
feedback to him (he did ask, though). I for one am also guilty of not 
following up with his work. He used to have it on his github account, 
but I can't seem to find it.


https://github.com/mcepl?tab=repositories


I was looking for something in Python, but all I got is either outdated, or 
non-complete.


I wish we had a better answer to give you, but unfortunately we don't.

___
qa-devel mailing list
qa-de...@lists.fedoraproject.org
https://admin.fedoraproject.org/mailman/listinfo/qa-devel

Re: Taskbot: TAP vs Subunit

[Lucas Meneghel Rodrigues]

On 10/31/2013 01:23 PM, Kamil Paral wrote:

= TAP =

TAP is not unittest-specific, and is human-readable plaintext format.

It also has just PASS/FAIL logic, but there is a possibility to add YAML
'metadata' to any result (since TAP v. 13).

The real issue with TAP is Python support.
There is a TAP-consumer library created as an example for PyParsing
, but it does not
support the v13 protocol, and is quite useless as such.
TAP-producer library for Python  is also using
the old version (i.e. no YAML extensions), and seems to be dead (2 years
since last update). It is also quite badly written.


Doesn't autotest support TAP results storage? How do they do it?

Lucas, can you comment? Thanks.



Here you can see an example:

$ client/autotest-local --tap client/tests/sleeptest/control
14:11:58 INFO | Writing results to 
/home/lmr/Code/autotest.git/autotest/client/results/default

14:11:58 INFO | Could not symlink init scripts (lack of permissions)
14:11:58 INFO | Not logging /proc/slabinfo (lack of permissions)
14:11:58 INFO | START			timestamp=1383235918	localtime=Oct 31 
14:11:58	
14:11:58 INFO | 	START	sleeptest	sleeptest	timestamp=1383235918 
localtime=Oct 31 14:11:58	

14:11:58 INFO | Not logging /proc/slabinfo (lack of permissions)
14:11:59 INFO | Not logging /proc/slabinfo (lack of permissions)
14:11:59 INFO | Not logging /var/log/messages (lack of permissions)
14:11:59 INFO | 		GOOD	sleeptest	sleeptest	timestamp=1383235919 
localtime=Oct 31 14:11:59	completed successfully
14:11:59 INFO | 	END GOOD	sleeptest	sleeptest	timestamp=1383235919 
localtime=Oct 31 14:11:59	
14:11:59 INFO | END GOOD			timestamp=1383235919	localtime=Oct 
31 14:11:59	
14:11:59 INFO | Report successfully generated at 
/home/lmr/Code/autotest.git/autotest/client/results/default/job_report.html


$ cd /home/lmr/Code/autotest.git/autotest/client/results/default/

$ ls
control  control.state  debug  job_report.html  meta.yml  sleeptest 
status  status.json  status.tap  sysinfo  tap.tar.gz


$ cat meta.yml
file_order:
  - status.tap
  - sleeptest/status.tap
  - sleeptest/keyval.tap

$ cat status.tap
1..2
ok 1 - sleeptest
ok 2 - job

$ cat sleeptest/status.tap
1..1
ok 1 - sleeptest

$ cat sleeptest/keyval.tap
1..2
ok 1 - results
  ---
  param-seconds: 1
  version: 1
  ...
ok 2 - results
  ---
  sysinfo-cmdline: BOOT_IMAGE=/vmlinuz-3.11.6-301.fc20.x86_64 
root=/dev/mapper/fedora-root ro rd.lvm.lv=fedora/swap rd.md=0 rd.dm=0 
rd.luks.uuid=luks-8c032338-feaa-456a-873c-a08c768b8861 
vconsole.keymap=us rd.lvm.lv=fedora/root rhgb quiet LANG=en_US.utf8

  sysinfo-memtotal-in-kb: 8061220
  sysinfo-phys-mbytes: 8192
  sysinfo-uname: 3.11.6-301.fc20.x86_64 #1 SMP Mon Oct 21 21:54:19 UTC 
2013 x86_64 x86_64 x86_64 GNU/Linux

  ...

___
qa-devel mailing list
qa-de...@lists.fedoraproject.org
https://admin.fedoraproject.org/mailman/listinfo/qa-devel

Re: Taskbot: TAP vs Subunit

[Lucas Meneghel Rodrigues]

On 10/31/2013 01:23 PM, Kamil Paral wrote:

= TAP =

TAP is not unittest-specific, and is human-readable plaintext format.

It also has just PASS/FAIL logic, but there is a possibility to add YAML
'metadata' to any result (since TAP v. 13).

The real issue with TAP is Python support.
There is a TAP-consumer library created as an example for PyParsing
, but it does not
support the v13 protocol, and is quite useless as such.
TAP-producer library for Python  is also using
the old version (i.e. no YAML extensions), and seems to be dead (2 years
since last update). It is also quite badly written.


Doesn't autotest support TAP results storage? How do they do it?


Autotest does support recording results in TAP format, due to the work 
made by a guy from AMD. Breaking the expectations that a TAP enabled 
test tool would just output tap on standard output, the autotest client 
can optionally produce files with the results in tap format, and those 
files can be further processed by other systems.


Let me make some runs here and show you examples.


Lucas, can you comment? Thanks.



___
qa-devel mailing list
qa-de...@lists.fedoraproject.org
https://admin.fedoraproject.org/mailman/listinfo/qa-devel