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