Source code for ax.utils.common.docutils
#!/usr/bin/env python3
# Copyright (c) Meta Platforms, Inc. and affiliates.
#
# This source code is licensed under the MIT license found in the
# LICENSE file in the root directory of this source tree.
# pyre-strict
"""Support functions for sphinx et. al"""
from collections.abc import Callable
from typing import Any, TypeVar
_T = TypeVar("_T")
# pyre-fixme[2]: Parameter annotation cannot contain `Any`.
# pyre-ignore[34]: T77127616
[docs]
def copy_doc(src: Callable[..., Any]) -> Callable[[_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:
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
return copy_doc