API doc

[jburel]

Infrastructure to get the API doc generated again
The API doc has not been available since the extraction of omero-py.
There is one remaining warning but the bulk of it should now work.
.rst files were generated using https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html
Documentation available at https://jburel-omero-py.readthedocs.io/en/latest/
The sphinx job will be removed when the switch to rtd is done
cc @sbesson

[sbesson]

The changes proposed to the code itself mostly extract license/ownership information out of the docstring and convert docstrings from the former epydoc format to rst markup. The new configuration file looks in line with the basic Sphinx configuration.

Overall, this is one of the reference documentation that was not migrated as part of the OMERO 5.6.0 work and publishing it at readthedocs would be a nice-to-have from my side. How far do you feel we are from being able to activate readthedocs and having a staging deployment of this PR for review?

[sbesson]

What the set of rst files generated by hand or is there a tool to update it?

[jburel]

Files were generated using https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html
Some files can probably be deleted. I have deleted some already

[jburel]

I will first activate on my rtd account to check. I had surprised previously when switching to rtd

[jburel]

Available at https://jburel-omero-py.readthedocs.io/en/latest/

[dominikl]

Looks good to me. But I refer to Seb for a final review.

[joshmoore]

Maybe the only thing to possibly discuss before introducing a new RTD landing page is if we want a hierarchical solution as with omero-guides?

[jburel]

@joshmoore I agree. I was thinking the same

[jburel]

minimally a link should be added to https://docs.openmicroscopy.org/omero/latest/developers/Python.html

[sbesson]

Maybe the only thing to possibly discuss before introducing a new RTD landing page is if we want a hierarchical solution as with omero-guides?

Based on the discussion in ome/omero-guides#23, I assume if we were to introduce hierarchical solution, we would go with subprojects rather than submodules?

A few thoughts:

• https://.readthedocs.io/projects//en/latest/ certainly has the advantage of bundling e.g. various OMERO plugins/apps and making all of them searchable together
• in that case is it possible to have <top-level> == omero i.e. put this component documentation as a sub-project of https://github.com/ome/omero-documentation/
• contradicting the considerations above, for decoupled Python components, the pattern of hosting the package at https://pypi.org/project/foo and the documentation at https://foo.readthedocs.io/ is fairly common

[jburel]

The problem with sub-projects if I remember correctly has been the "search" aspect but I will have to refresh things

[sbesson]

The problem with sub-projects if I remember correctly has been the "search" aspect but I will have to refresh things

My memory is that subprojects would allow cross-component search as there should be a shared index. But the limitation that was pointed out for the OMERO guides was the loss of the hierarchy in the left-hand panel menu

[jburel]

The problem with sub-projects if I remember correctly has been the "search" aspect but I will have to refresh things

My memory is that subprojects would allow cross-component search as there should be a shared index. But the limitation that was pointed out for the OMERO guides was the loss of the hierarchy in the left-hand panel menu

The "lost of context" happens when you go in the "subproject".
Also the search did not work as advertised i.e. search when in subproject only search in subproject leading to confusion by some users

[sbesson]

Is there a consensus on the next steps here?

Assuming we have this API documentation published somewhere, would we start updating https://omero.readthedocs.io/en/stable/developers/Python.html with cross-references to the corresponding API links? Or is the idea to migrate the content of this page into the OMERO.py documentation e.g. as library usage examples accompanying the auto-generated API reference documentation?

[jburel]

I think it will be easier to add links to https://omero.readthedocs.io/en/stable/developers/Python.html. Migrating the pages will require some wrangling and it is not really what we discussed a while back

[sbesson]

I understand the domain name still remains to be settled. But conceptually big 👍 from my side to having this auto-generated API documentation published somewhere. Once it is available, we can start cross-linking to it from the relevant pages under https://github.com/ome/omero-documentation

[jburel]

Okay so I will migrate the doc to https://omero-py.readthedocs.io/
and fix some formatting issues in follow-up PR

[jburel]

no objection to go for https://omero-py.readthedocs.io/?

[jburel]

Thanks merging and deploying it

[jburel]

https://omero-py.readthedocs.io/en/latest/ is now available.
Stable will require a tag with the rtd conversion. Still some cleaning to do in the code to fix the doc layout.