def test_dedent(text):
"""Test that dedentation works, indent first so that there are some spaces to dedent"""
dedented_text = "\n" + console.dedent(console.indent(text, 8),
num_spaces=3)
num_lines = dedented_text.count("\n")
assert dedented_text.count("\n ") == text.count(
"\n ") # 6 spaces indent
assert dedented_text.count("\n ") == num_lines # 5 spaces indent
def doc(
package_name: str,
plugin_name: str,
part: Optional[str] = None,
prefix: Optional[str] = None,
long_doc: bool = True,
include_details: bool = False,
) -> str:
"""Document one plug-in
If the plug-in is not part of the package an UnknownPluginError is raised.
If there are several functions registered in a plug-in and `part` is not
specified, then the first function registered in the plug-in will be
documented.
Args:
package_name: Name of package containing plug-ins.
plugin_name: Name of the plug-in, i.e. the module containing the plug-in.
part: Name of function to call within the plug-in (optional).
prefix: Prefix of the plug-in name, used if the plug-in name is unknown (optional).
long_doc: Whether to return the long doc-string or the short one-line string (optional).
include_details: Whether to include development details like parameters and return values (optional).
Returns:
Documentation of the plug-in.
"""
# Get Plugin-object and pick out doc-string
plugin_name = load(package_name, plugin_name, prefix=prefix)
part = "__default__" if part is None else part
try:
plugin = _PLUGINS[package_name][plugin_name][part]
except KeyError:
raise UnknownPluginError(
f"Plugin {part!r} not found for {plugin_name!r} in {package_name!r}"
) from None
doc = plugin.function.__doc__ if plugin.function.__doc__ else ""
if long_doc:
# Strip short description and indentation
doc = console.dedent("\n\n".join(doc.split("\n\n")[1:]))
lines = doc.rstrip().splitlines()
# Stop before Args:, Returns: etc if details should not be included
idx_args = len(lines)
if not include_details:
re_args = re.compile(
"(Args:|Returns:|Details:|Examples?:|Attributes:)$")
try:
idx_args = [re_args.match(l) is not None
for l in lines].index(True)
except ValueError:
pass
return "\n".join(lines[:idx_args]).strip()
else:
# Return short description
return doc.split("\n\n")[0].replace("\n", " ").strip()
def _header(fid):
title = "Where SISE comparison"
user_info = util.get_user_info()
user = user_info.get("name", user_info["user"])
fid.write(
console.dedent(f"""---
title: {title}
author: Where v{where.__version__} [{user}]
date: {datetime.now():%Y-%m-%d}
---
"""))
fid.write("\\newpage\n\n")
def test_dedent_all(one_paragraph_ragged_left):
"""If not specifying num_spaces, dedent all the way"""
dedented_text = console.dedent(console.indent(one_paragraph_ragged_left,
7))
assert dedented_text == one_paragraph_ragged_left
def test_dedent_too_much(one_paragraph_ragged_left):
"""If dedenting more than existing spaces, only dedent existing spaces"""
dedented_text = console.dedent(console.indent(one_paragraph_ragged_left,
2),
num_spaces=4)
assert dedented_text == one_paragraph_ragged_left
