Source code for ax.utils.common.docutils

#!/usr/bin/env python3
# Copyright (c) Facebook, Inc. and its affiliates. All Rights Reserved.
# pyre-strict

"""Support functions for sphinx et. al
"""


from typing import TypeVar


_T = TypeVar("_T")


[docs]def copy_doc(src: _T) -> _T:
    """A decorator that copies the docstring of another object

    Since ``sphinx`` actually loads the python modules to grab the docstrings
    this works with both ``sphinx`` and the ``help`` function.

    .. code:: python

      class Cat(Mamal):

        @property
        @copy_doc(Mamal.is_feline)
        def is_feline(self) -> true:
            ...
    """
    # It would be tempting to try to get the doc through the class the method
    # is bound to (via __self__) but decorators are called before __self__ is
    # assigned.
    # One other solution would be to use a decorator on classes that would fill
    # all the missing docstrings but we want to be able to detect syntactically
    # when docstrings are copied to keep things nice and simple

    if src.__doc__ is None:
        # pyre-fixme[16]: `_T` has no attribute `__qualname__`.
        raise ValueError(f"{src.__qualname__} has no docstring to copy")

    def copy_doc(dst: _T) -> _T:
        if dst.__doc__ is not None:
            # pyre-fixme[16]: `_T` has no attribute `__qualname__`.
            raise ValueError(f"{dst.__qualname__} already has a docstring")
        dst.__doc__ = src.__doc__
        return dst

    # pyre-fixme[7]: Expected `_T` but got `Callable[[_T], _T]`.
    return copy_doc