Attributes decorated with @cached_property are not denoted as properties in documentation

[andykee]

Properties are denoted as such in the documentation. See nseg and pixelscale below.

Unfortunately, although phase behaves like a property, because it is actually decorated with @cached_property, which implements the descriptor protocol but has no real relationship to the Python property, Sphinx doesn't identify these attributes a properties.

Sphinx uses a method called isproperty() to tag things as properties. I'm wondering if it is easy to develop a simple extension to rework the isproperty() method to return

isinstance(obj, (property, lentil.modeltools.cached_property))

[andykee]

I've done some more research on this:

• Sphinx offers docstring preprocessing that seemed promising, but it doesn't appear that it's possible to modify the type of each detected object.

• I also looked into trying to spoof the type of cached_property, which isn't promising.

Unfortunately, I think the only way to do this is to use the property() function definition for the class attributes that are currently defined as "cached properties". For Plane.phase, it would look something like this:

class Plane:
    def __init__(self, phase=0, ...):
        self._phase = np.asarray(phase)
        ...

    @property
    def phase(self):
        if self.cache.get('phase') is not None:
            return self.cache.get('phase')
        else:
            return self._phase

    @phase.setter
    def phase(self, value):
        self.cache.delete('phase')
            if value is not None:
                self._phase = np.asarray(value)
            else:
                self._phase = None

This will eliminate the use of the cached_property decorator in the code, but it will still be useful when users subclass Plane and define custom phase attributes.