ComputeUnit API is not documented

[oleweidner]

http://saga-project.github.io/BigJob/sphinxdoc/library/index.html#computeunit

... section 5.2.2. doesn't really get me any further.

In general I think that the Library documentation (which is equivalent with the P* API description!) needs a lot of work. It is not very useful in its current state. I frequently have to pull up the BigJob source code in order to check with methods are available on an object, etc...

IMHO this needs immediate attention - definitely before the San Diego tutorial.

[melrom]

Yeah I agree - I find the library/API documentation to be almost unreadable. Would like to request assistance on this. It's not exactly as 'easy' as saga-python, because BigJob was created in 'research' mode and is not very... self-documenting and also somewhat difficult to 'organize' using Sphinx.

The sphinx docs were modeled after (http://saga-project.github.io/BigJob/apidoc/), but because of the way Sphinx does things, I had to self-document a lot of the code. This self-documenting and also the auto-documenting thing came out in general looking like a bunch of spaghetti. I am not sure if its our sphinx layout (i.e. maybe the pretty black/blue/gray layout that we have is just not conducive to actual API documentation), or the BigJob code/function documentation, or a combination of the two, but I basically need help formulating a plan here.

In general, I think it's a combination but the current Sphinx layout is poorly designed for this sort of documentation. Checkout the theme SQLAlchemy has created: http://docs.sqlalchemy.org/en/rel_0_5/reference/sqlalchemy/pooling.html

Notice how the properties/parameters are organized easily and quite readable.

[melrom]

I changed the sphinx documentation to use the "Read the Docs" layout. This has greatly improved the readability from a layout perspective, although, as mentioned a couple months ago, I have requested assistance with the content of the API docs - I simply do not have the time or manpower to be solely responsible.

[marksantcroos]

Hi Melissa,

I’m willing to help out with the API documentation, as I’ve found some issues recently while looking things up myself.

How does one go about changing the documentation? Is this using the external read-the-docs now? So I only need to document the code itself?

Thanks!

Gr,

Mark

On 05 Dec 2013, at 22:50 , Melissa notifications@github.com wrote:

I changed the sphinx documentation to use the "Read the Docs" layout. This has greatly improved the readability from a layout perspective, although, as mentioned a couple months ago, I have requested assistance with the content of the API docs - I simply do not have the time or manpower to be solely responsible.

— Reply to this email directly or view it on GitHub.