API Documentation Improvements

[oweidner]

Improvements:

• Each 'main' example for a class should be (a) completely runnable using fork://localhost and testable with doctest: http://docs.python.org/library/doctest.html. The idea is that anyone should be able to copy and paste the example into a text editor and run it!
• All text should be thoroughly spell-checked again.
• All code examples should adhere to http://www.python.org/dev/peps/pep-0008/ and please use function() instead of function ()
• All code examples should be checked again. There is an astonishing amount of sloppiness and errors in the examples!

  Problems:

• Attribute interface: Examples are completely wrong and neither written in C++ nor Python. Use 'doctest' for main example. attribute_is_vector uses 'fi' as a keyword?!? list_attributes() dict example doesn't throw. Examples and comparison with dict is really confusing!
• Context: Use 'doctest' for main example. Instead of c['Type'] , c['UserCert'] use c.type, c.usercert as in all other examples, i.e., https://github.com/saga-project/bliss/blob/master/examples/job-api/pbs_via_ssh_bfast_job.py. Properties / class variables don't seem to be documented.
• Error: Needs some documentation + doctest-able example
• Exception: Add doctest-able example
• Session: Use c.type instead of c['UserCert'] syntax. Make doctest-able.
• Url : Is missing description and examples.
• job.Description: Main example should be doctest-able. Please remove all "Example (using the attribute interface):" examples.

[andre-merzky]

Each 'main' example for a class should be (a) completely runnable using fork://localhost and testable with doctest: http://docs.python.org/library/doctest.html. The idea is that anyone should be able to copy and paste the example into a text editor and run it!

I am not sure that doctest is the right thing to do here. This sounds great in theory, but all examples would need to be formatted as interactive sessions, and cannot contain blank lines for formatting etc -- that would make the longer examples (which your comment meant) quite difficult to read. Also, output verification does not help much, as SAGA commands are usually silent.

So, all that doctest gives you is a semantic check. Which is nice, no doubt about it, but I am not sure this is a good tradeoff?

spellchecked:

I have a spell checker turned on -- it likes what it finds so far ;-) Of course I'll look over it again, in particular in the code sections, but please fix what you stumble over, because I obviously missed it, and will likely miss it again...

code formatting in examples

Same as for spell checking - is supposed to be the case... will check again.

attribute interface:

comparison with dict is really confusing

So, why do we have two approaches? I am totally fine removing either one, and it was really tedious to follow your suggestion to always document both ;-) Or maybe I misunderstood you...

c['Type'] -> c.type etc.

Hmm, why do we have two different approaches, if one is not to be documented/used?

Cheers, Andre.

[andre-merzky]

Each 'main' example for a class should be (a) completely runnable using fork://localhost:

So, I started doing the respective changes, but really think this is a bad idea. For example, the code describing the job package shows how to run a parallel blast on a GRAM endpoint -- a perfectly valid and relevant example for our user community. Changing that to a /bin/date on fork://localhost makes the documentation, well, not useless, but irrelevant...

So, I did the changes for all examples, but not for the job package doc, and also not for session, context and exception...

[oweidner]

Andre,

as you know, Bliss doesn't even have a plug-in for GRAM. It is completely pointless to use this in an example. Please write examples that are functional and make sense in the current Bliss context.

Thanks, Ole

On May 22, 2012, at 7:26 AM, Andre Merzky wrote:

Each 'main' example for a class should be (a) completely runnable using fork://localhost:

So, I started doing the respective changes, but really think this is a bad idea. For example, the code describing the job package shows how to run a parallel blast on a GRAM endpoint -- a perfectly valid and relevant example for our user community. Changing that to a /bin/date on fork://localhost makes the documentation, well, not useless, but irrelevant...

So, I did the changes for all examples, but not for the job package doc...

---

Reply to this email directly or view it on GitHub: https://github.com/saga-project/bliss/issues/45#issuecomment-5845632

[andre-merzky]

I think I fixed all of the items above, apart from the items raised above. So, I'll close that ticket. Feel free to open new tickets for individual problems of course!