pitrou commented on a change in pull request #12076:
URL: https://github.com/apache/arrow/pull/12076#discussion_r783866373
##########
File path: python/pyarrow/compute.py
##########
@@ -105,66 +117,70 @@ def _decorate_compute_function(wrapper, exposed_name,
func, options_class):
doc_pieces = []
# 1. One-line summary
- cpp_doc = func._doc
summary = cpp_doc.summary
if not summary:
arg_str = "arguments" if func.arity > 1 else "argument"
summary = ("Call compute function {!r} with the given {}"
.format(func.name, arg_str))
- description = cpp_doc.description
- arg_names = _get_arg_names(func)
-
- doc_pieces.append("""\
- {}.
-
- """.format(summary))
+ doc_pieces.append(f"{summary}.\n\n")
# 2. Multi-line description
+ description = cpp_doc.description
if description:
- doc_pieces.append("{}\n\n".format(description))
+ doc_pieces.append(f"{description}\n\n")
doc_addition = _compute_docstrings.function_doc_additions.get(func.name)
# 3. Parameter description
- doc_pieces.append("""\
+ doc_pieces.append(dedent("""\
Parameters
----------
- """)
+ """))
+ # 3a. Compute function parameters
+ arg_names = _get_arg_names(func)
for arg_name in arg_names:
if func.kind in ('vector', 'scalar_aggregate'):
arg_type = 'Array-like'
else:
arg_type = 'Array-like or scalar-like'
- doc_pieces.append("""\
- {} : {}
- Argument to compute function
- """.format(arg_name, arg_type))
+ doc_pieces.append(f"{arg_name} : {arg_type}\n")
+ doc_pieces.append(" Argument to compute function.\n")
+ # 3b. Compute function option values
if options_class is not None:
- options_sig = inspect.signature(options_class)
- for p in options_sig.parameters.values():
- doc_pieces.append("""\
- {0} : optional
- Parameter for {1} constructor. Either `options`
- or `{0}` can be passed, but not both at the same time.
- """.format(p.name, options_class.__name__))
- doc_pieces.append("""\
- options : pyarrow.compute.{0}, optional
- Parameters altering compute function semantics.
- """.format(options_class.__name__))
-
- doc_pieces.append("""\
+ options_class_doc = _scrape_options_class_doc(options_class)
+ if options_class_doc:
+ for p in options_class_doc.params:
+ doc_pieces.append(f"{p.name} : {p.type}\n")
+ for s in p.desc:
+ doc_pieces.append(f" {s}\n")
+ else:
+ warnings.warn(f"Options class {options_class.__name__} "
+ f"does not have a docstring", RuntimeWarning)
+ options_sig = inspect.signature(options_class)
+ for p in options_sig.parameters.values():
+ doc_pieces.append(dedent("""\
+ {0} : optional
+ Parameter for {1} constructor. Either `options`
+ or `{0}` can be passed, but not both at the same time.
+ """.format(p.name, options_class.__name__)))
+ doc_pieces.append(dedent(f"""\
+ options : pyarrow.compute.{options_class.__name__}, optional
+ Alternative way of passing options.
+ """))
+
+ doc_pieces.append(dedent("""\
memory_pool : pyarrow.MemoryPool, optional
If not passed, will allocate memory from the default memory pool.
- """)
+ """))
# 4. Custom addition (e.g. examples)
if doc_addition is not None:
- doc_pieces.append("\n{}\n".format(doc_addition.strip("\n")))
+ doc_pieces.append("\n{}\n".format(dedent(doc_addition).strip("\n")))
- wrapper.__doc__ = "".join(dedent(s) for s in doc_pieces)
+ wrapper.__doc__ = "".join(s for s in doc_pieces)
Review comment:
Indeed :-)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
