def test_process_docstring_class(app):
lines = [
"Does something.",
'',
":param foo: An argument.",
":param bar: Another argument.",
":param show: Whether to print the result.",
":param coloured_output: Whether to use coloured output.",
'',
]
class MyClass:
def __init__(self, foo, bar=None, show=True, coloured_output=False):
pass
process_docstring(app, '', '', MyClass, {}, lines)
assert lines == [
"Does something.",
'',
":param foo: An argument.",
":param bar: Another argument.",
" Default :py:obj:`None`.",
":param show: Whether to print the result.",
" Default :py:obj:`True`.",
":param coloured_output: Whether to use coloured output.",
" Default :py:obj:`False`.",
'',
]
def test_process_docstring_property(app):
lines = [
"Does something.",
'',
":param foo: An argument.",
":param bar: Another argument.",
":param show: Whether to print the result.",
":param coloured_output: Whether to use coloured output.",
'',
]
class MyClass:
@property
def my_prop(self) -> None:
return None
process_docstring(app, '', '', MyClass.my_prop, {}, lines)
assert lines == [
"Does something.",
'',
":param foo: An argument.",
":param bar: Another argument.",
":param show: Whether to print the result.",
":param coloured_output: Whether to use coloured output.",
'',
]
def test_process_docstring_no_final_newline(app):
lines = [
"Does something.",
'',
":param foo: An argument.",
":param bar: Another argument.",
":param show: Whether to print the result.",
":param coloured_output: Whether to use coloured output.",
]
def my_func(foo, bar=None, show=True, coloured_output=False):
pass
process_docstring(app, '', '', my_func, {}, lines)
assert lines == [
"Does something.",
'',
":param foo: An argument.",
":param bar: Another argument.",
" Default :py:obj:`None`.",
":param show: Whether to print the result.",
" Default :py:obj:`True`.",
":param coloured_output: Whether to use coloured output.",
" Default :py:obj:`False`.",
'',
]
def test_process_docstring_underscores_class(app):
lines = [
"A factory function to return a custom list subclass with a name.",
'',
r":param name\_: The name of the list",
":default foo: bar",
'',
":return:",
]
class Underscore:
def __init__(self, name_: str = "NamedList"):
pass
process_docstring(app, '', '', Underscore, {}, lines)
assert lines == [
"A factory function to return a custom list subclass with a name.",
'',
r":param name\_: The name of the list.",
" Default ``'NamedList'``.",
'',
":return:",
'',
]
def test_process_docstring_attrs(app):
lines = dedent(Device.__doc__).split('\n') # type: ignore
process_docstring(app, '', '', Device, {}, lines)
assert lines == [
'',
"Represents a device in a :class:`~.AcqMethod:`.",
'',
":param device_id: The ID of the device",
":param display_name: The display name for the device.",
":param rc_device: Flag to indicate the device is an RC Device. If :py:obj:`False` the device is an SCIC.",
" Default :py:obj:`False`.",
":param configuration: List of key: value mappings for configuration options.",
" Default ``[]``.",
'',
]
def test_process_docstring_suppress(app):
lines = [
"A factory function to return a custom list subclass with a name.",
'',
":param name: The name of the list.",
":no-default name:",
'',
":return:",
]
process_docstring(app, '', '', namedlist, {}, lines)
assert lines == [
"A factory function to return a custom list subclass with a name.",
'',
":param name: The name of the list.",
'',
":return:",
'',
]
def test_process_docstring_missing_fullstop(app):
lines = [
"A factory function to return a custom list subclass with a name.",
'',
":param name: The name of the list",
'',
":return:",
]
process_docstring(app, '', '', namedlist, {}, lines)
assert lines == [
"A factory function to return a custom list subclass with a name.",
'',
":param name: The name of the list.",
" Default ``'NamedList'``.",
'',
":return:",
'',
]
def test_process_docstring_override(app):
lines = [
"A factory function to return a custom list subclass with a name.",
'',
":param name: The name of the list.",
":default name: py:obj:`True`",
'',
":return:",
]
process_docstring(app, '', '', namedlist, {}, lines)
assert lines == [
"A factory function to return a custom list subclass with a name.",
'',
":param name: The name of the list.",
" Default py:obj:`True`.",
'',
":return:",
'',
]
def test_process_docstring_demo(app):
lines = [
":param a: No default.",
":param b: A float.",
":param c: An empty string.",
":param d: A space (or a smiley face?)",
":param e: A string.",
":param f: A Tuple.",
":param g: A Decimal.",
":param h: An int.",
":param i: Default None.",
":param j: Overridden default.",
":default j: ``[]``",
":param k: Suppressed default.",
":no-default k:",
":param l: This is a really long description.",
" It spans multiple lines.",
" The quick brown fox jumps over the lazy dog.",
" The default value should be added at the end regardless.",
":param m: Tab.",
":param n: This argument's default value is undefined.",
'',
]
def demo(
a: Any,
b: float = 0.0,
c: str = '',
d: str = ' ',
e: str = "hello world",
f: Tuple = (),
g: Decimal = Decimal("12.34"),
h: int = 1234,
i: Optional[List[str]] = None,
j: Optional[List[str]] = None,
k: Optional[List[str]] = None,
l: str = '',
m: str = '\t',
n: Any = ...,
):
pass
process_docstring(app, '', '', demo, {}, lines)
assert lines == [
":param a: No default.",
":param b: A float.",
" Default ``0.0``.",
":param c: An empty string.",
" Default ``''``.",
":param d: A space (or a smiley face?).",
" Default ``'␣'``.",
":param e: A string.",
" Default ``'hello world'``.",
":param f: A Tuple.",
" Default ``()``.",
":param g: A Decimal.",
" Default ``Decimal('12.34')``.",
":param h: An int.",
" Default ``1234``.",
":param i: Default None.",
" Default :py:obj:`None`.",
":param j: Overridden default.",
" Default ``[]``.",
":param k: Suppressed default.",
":param l: This is a really long description.",
" It spans multiple lines.",
" The quick brown fox jumps over the lazy dog.",
" The default value should be added at the end regardless.",
" Default ``''``.",
":param m: Tab.",
r" Default ``'\t'``.",
":param n: This argument's default value is undefined.",
'',
]
