search

ome / omero-scripts

Core OMERO Scripts
https://pypi.org/project/omero-scripts/
12 stars 32 forks source link

readthedocs build with autodoc #176

Closed will-moore closed 3 years ago

will-moore commented 3 years ago

This is the result of attempting to learn how to build Sphinx docs with autodoc to include docs built from docstrings.

Currently, my master branch is being built with https://readthedocs.org/projects/will-moore-omero-scripts/ And the built docs are at https://will-moore-omero-scripts.readthedocs.io/en/latest/

This is just building docs for one Kymograph script so far... Since this repo doesn't have any requirements.txt yet, I created one under docs/requirements.txt. Seems to install omero-py fine.

But, when I try to build locally, it fails to import omero, although it is installed in my current conda env.

$ cd docs
$ make html
Running Sphinx v3.1.2
WARNING: html_static_path entry '_static' does not exist
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: 0 added, 1 changed, 0 removed
reading sources... [100%] index                                                                                                                                                                                                
WARNING: autodoc: failed to import module 'Kymograph'; the following exception was raised:
No module named 'omero'
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index                                                                                                                                                                                                 
generating indices...  genindexdone
writing additional pages...  searchdone
copying static files... ... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 2 warnings.

cc @manics @joshmoore

joshmoore commented 3 years ago

And the built docs are at https://will-moore-omero-scripts.readthedocs.io/en/latest/

Nice! (even if very Kymograph focused :wink:)

It's a shame that it requires all the sphinx boilerplate though.

will-moore commented 3 years ago

I don't know that it requires all the sphinx boilerplate. That's just what you get from following $ sphinx-quickstart https://www.sphinx-doc.org/en/master/usage/quickstart.html

Trying to build a module instead of a single script: https://github.com/ome/omero-scripts/pull/176/commits/b7351ac4160c44eb1616a574e089bbe5fe30db05 fails to include any autodoc output, although the docs build passes: https://readthedocs.org/projects/will-moore-omero-scripts/builds/12100895/ Also, can't test the build locally (as mentioned above).

jburel commented 3 years ago

How did you create your conda env?

will-moore commented 3 years ago

I think I followed the docs Python bindings page install instructions.

jburel commented 3 years ago

so you are using python3, just trying to narrow down the problem

will-moore commented 3 years ago

Travis is failing due to integration tests failing with omero.NoProcessorAvailable: exception ::omero::NoProcessorAvailable. OK to ignore for now.

will-moore commented 3 years ago

Yes, python 3.

will-moore commented 3 years ago

It seems that sphinx is not designed to auto-document a whole project (https://groups.google.com/g/sphinx-users/c/ZZTFVGbW5Q4) So I reverted to specifying individual scripts in the last commit, adding a new docs/analysis_scripts.rst page and adding this to the toctree. The page was built OK (https://will-moore-omero-scripts.readthedocs.io/en/latest/analysis_scripts.html) but I don't see any link to it (no toctree) in the home page https://will-moore-omero-scripts.readthedocs.io/en/latest/index.html

@jburel Any ideas what I'm doing wrong here?

joshmoore commented 3 years ago

It seems that sphinx is not designed to auto-document a whole project (https://groups.google.com/g/sphinx-users/c/ZZTFVGbW5Q4)

Hmm... maybe I'm misunderstanding, but I'm pretty sure it should be possible to do what you want, though it may require placeholders under docs/... which point to given classes and/or modules like https://github.com/spacetx/starfish/blob/master/docs/source/api/spots/index.rst#detecting-pixels