Tables documentation partial rewrite 9957 #193
Conversation
Added description of parameters for creating OMERO.Tables columns. Added links to existing sample code.
Added documentation for the main OMERO.tables methods Use :class:, :func:, :attribute: roles USe sphinx parameter type specifications, expanded getWhereList
|
2 primary thoughts:
/cc @sbesson & @rleigh-dundee |
|
Getting sphinx to build the documentation is trivial; I can open a PR for that almost immediately--just need to dig out the patch. The main effort is in updating the comments; since I'm not familiar with the API, this should really be done by someone familiar with the code. It probably also needs doing in openmicroscopy.git or else it will break a standalone docs build. In general though, the API documentation should probably go in the code where possible, though there will be an initial effort to get the comments converted. |
A lot of the docs will be in the Ice definition files- is it straightforward to include Sphinx documentation in them?
I thought I'd keep it there for now since the Tables docs are quite short, as they get expanded it can be made a top level heading. |
|
I doubt that we can get sphinxdocs into the ice definition, but we can embed doxygen. (See |
|
So should I move the class/method docs into the Ice file and reference them in the sphinxdocs, or leave it for now? |
|
@manics, to some extent that's up to you. Long-term, much of the gory details should be in the ice file. If you think you could get something with links to the slice2html working from tables.txt, then by all means. Otherwise, we can do that later. |
|
In that case I'd rather wait until we decide on the grand plan for the documentation. |
|
Looks like we need to have a chat about this at some point. I'm wondering if it is a situation like the BF developer docs where we want to reference code files in the docs but I probably need someone to talk me through this specific case. |
|
|
||
| .. class:: omero.grid.Column | ||
|
|
||
| The base class for column types which permit returning arrays of |
There was a problem hiding this comment.
Ah, apologies Simon, I parsed that incorrectly and thought the class was permitting rather than the column type.
|
I had a go at writing a slice2rst utility: More a proof-of-concept at the moment, question is whether it's worth the effort of developing and integrating it. |
|
I don't feel qualified to answer this. From my POV, as long as there is something in the sphinx docs to point people to the right location, I happy for this level of developer documentation to be stored wherever the actual developers think is easier. |
|
Sorry, I should've targetted this to @joshmoore |
|
It's fine, I wasn't sure whether you were asking me or not, just thought I'd clarify my position either way. |
|
Saw the proof-of-concept which is probably a good mid- or long-term solution. For the moment, I'd probably just fix your s/z's (:smile:), and we can continue the rst discussion on-list and in-meeting. |
|
s/z fixed. |
|
👍 |
Tables documentation partial rewrite 9957
This was origingally a partial rewrite of the tables documentation including the new array columns from PR ome/openmicroscopy#538. Since it may be held back from the next release I'll split the docs PR into two, this one covers doc changes relating to the existing tables functionality:
Analysisin the TOC.If I don't open this now I'll probably forget after Christmas.