-
Notifications
You must be signed in to change notification settings - Fork 33
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
API doc #330
API doc #330
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?
:maxdepth: 4 | ||
:caption: Contents: | ||
|
||
omero |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What the set of rst files generated by hand or is there a tool to update it?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
I will first activate on my rtd account to check. I had surprised previously when switching to rtd |
Available at https://jburel-omero-py.readthedocs.io/en/latest/ |
Looks good to me. But I refer to Seb for a final review. |
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? |
@joshmoore I agree. I was thinking the same |
minimally a link should be added to https://docs.openmicroscopy.org/omero/latest/developers/Python.html |
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:
|
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". |
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? |
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
Okay so I will migrate the doc to https://omero-py.readthedocs.io/ |
no objection to go for https://omero-py.readthedocs.io/? |
Thanks merging and deploying it |
https://omero-py.readthedocs.io/en/latest/ is now available. |
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.htmlDocumentation 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