openmicroscopy/openmicroscopy — pull request #2910 by sbesson (2014-08-05 20:47:14+00:00)
Title: Fix warnings in Sphinx API generation (rebased onto develop)

This is the same as gh-2899 but rebased onto develop.

----

This PR starts cleaning many of the warnings arising during the Sphinx API generation. In particular
- remove non-working block in the main index.rst
- fix docstrings across a couple of modules
- fix omero.gateway to use the Sphinx info fields instead of epydoc markers - see http://sphinx-doc.org/domains.html#info-field-lists. This should return properly parsed parameters/returns in the generated Sphinx API.

Note I realized the last item is a very large change (although these are almost exclusively docstring substitutions of type `@type` -> `:type`). Happy to split it into multiple commits if that makes it clearer and/or do it post 5.0.3.

Items not modified as apart of this PR (i.e. that should still show up as warnings in the build console):
- broken Glencoe headers (`omero/columns.py`, `omero/rtypes.py`) /cc @joshmoore
- all auto-generated Python modules. Due to the format imposed by Ice's `slice2py` parsing these docstrings properly will likely require configuring http://sphinx-doc.org/latest/ext/napoleon.html which will be bundled with Sphinx 1.3
- `autodoc: failed to import module...` errors. This is mostly due to running the build within a virtual environment (without numpy ...) and should be fixed at the CI level instead. /cc @kennethgillen
- OMERO.web modules