Documentation #61635
openLibrbd (Python) rbd.Image API reference missing most methods
0%
Description
I'm not sure if there is any way to fix this but ...
The Librbd (Python) documentation for the rbd.Image module currently contains only two methods [1]:
and I think this might be because of the @requires_not_closed [2] decorator on most of the methods:
def requires_not_closed(f):
def wrapper(self, *args, **kwargs):
self.require_not_closed()
return f(self, *args, **kwargs)
which calls
def require_not_closed(self):
"""
Checks if the Image is not closed
:raises: :class:`InvalidArgument`
"""
if self.closed:
raise InvalidArgument("image is closed")
and self.closed defaults to True:
def __init__(self, ioctx, name=None, snapshot=None,
read_only=False, image_id=None, _oncomplete=None):
"""
Open the image at the given snapshot.
Specify either name or id, otherwise :class:`InvalidArgument` is raised.
If a snapshot is specified, the image will be read-only, unless
:func:`Image.set_snap` is called later.
If read-only mode is used, metadata for the :class:`Image`
object (such as which snapshots exist) may become obsolete. See
the C api for more details.
To clean up from opening the image, :func:`Image.close` should
be called. For ease of use, this is done automatically when
an :class:`Image` is used as a context manager (see :pep:`343`).
:param ioctx: determines which RADOS pool the image is in
:type ioctx: :class:`rados.Ioctx`
:param name: the name of the image
:type name: str
:param snapshot: which snapshot to read from
:type snapshot: str
:param read_only: whether to open the image in read-only mode
:type read_only: bool
:param image_id: the id of the image
:type image_id: str
"""
name = cstr(name, 'name', opt=True)
image_id = cstr(image_id, 'image_id', opt=True)
snapshot = cstr(snapshot, 'snapshot', opt=True)
self.closed = True
So those methods with the decorator on them end up not being returned when the doc is generated and they get left out of the doc.
[1] https://docs.ceph.com/en/quincy/rbd/api/librbdpy/#rbd.Image
[2] https://github.com/ceph/ceph/blob/219d315/src/pybind/rbd/rbd.pyx#L2768
Files
Updated by Ilya Dryomov 11 months ago
Hi Melanie,
Do you have a link handy to the documentation snippet explaining the interaction with decorators here, as relevant to "because of the @requires_not_closed decorator on most of the methods"?
Updated by melanie witt 11 months ago
Hi Ilya,
I'm not aware of official documentation that directly describes interactions with decorators, however,
I had noticed that the only two methods for which documentation was generated have no decorator, so I googled to see if I could find anything related to sphinx doc generation and decorators and came across this:
https://github.com/sphinx-doc/sphinx/issues/10310
which led me to guess maybe a similar thing is happening with the rbd.Image docs.
The docs for autodoc [1]2 say:
:members: (no value or comma separated list) If set, autodoc will generate document for the members of the target module, class or exception. For example: .. automodule:: noodle :members: will document all module members (recursively), and .. autoclass:: Noodle :members: will document all class member methods and properties.
and this is where that's used for the librbdpy docs [3]:
API Reference
=============
.. automodule:: rbd
:members: RBD, Image, SnapIterator
There's a note later in the sphinx doc that I think indirectly refers to how decorated methods docs are generated:
Note
If you document decorated functions or methods, keep in mind that autodoc retrieves its docstrings by importing the module and inspecting the doc attribute of the given function or method. That means that if a decorator replaces the decorated function with another, it must copy the original doc to the new function.
i.e. it will inspect and in the case of decorated methods, it will get what the decorator returns.
I also came across this issue:
https://github.com/sphinx-doc/sphinx/issues/3783
where someone said functools.wraps didn't work for them for returning the decorated method signature but they found a different workaround.
I'm not sure if functools.wraps would be enough to fix the librbdpy rbd.Image doc generation. I tried to sphinx-build the docs locally to test it but failed due to dependency issues I couldn't figure out.
Thanks for replying. I felt motivated to dig into this docs problem in hopes of helping other people trying to use the python bindings, including my future self :)
[1] https://www.sphinx-doc.org/en/master/tutorial/automatic-doc-generation.html
[2] https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#directive-option-automodule-members
[3] https://github.com/ceph/ceph/blob/abcfa44/doc/rbd/api/librbdpy.rst#L84-L85