Link API docs to user guide and other examples #5816
Comments
|
I think doing both is always appreciated: short "how to" with a common pattern or two and then a "see also". |
|
See https://github.com/pydata/xarray/blob/main/xarray/core/dataset.py#L2022 for how to link the doc string to other parts of the docs |
|
I agree, this is would be really helpful. There's lots to do, though: a small script reports about 170 functions / methods without example sections (and 6 numpy wrappers), and all others could use reviews: analysis scriptimport itertools
import numpy as np
import xarray as xr
def public_api(obj, base_name):
api = dir(obj)
public_api = tuple(name for name in api if not name.startswith("_"))
public_api_objects = {name: getattr(obj, name) for name in public_api}
# uppercase indicates classes
public_functions = {
f"{base_name}.{name}": obj
for name, obj in public_api_objects.items()
if not name[0].isupper() and callable(obj)
}
return public_functions
def is_dict_method(fqn):
*_, name = fqn.split(".")
return hasattr(dict, name)
def has_section(docstring, name):
lines = docstring.split("\n")
marker = "-" * len(name)
for current, next in itertools.zip_longest(lines, lines[1:]):
if next is None or next.strip() != marker:
continue
if current.strip() == name:
return True
return False
def is_numpy_wrapper(fqn, docstring):
*_, name = fqn.split(".")
segment = f"Refer to `numpy.{name}` for full documentation."
shortened_segment = f"Refer to `numpy.{name[:4]}` for full documentation."
if segment in docstring or shortened_segment in docstring:
return True
numpy_func = getattr(np, name, None)
if numpy_func is None:
return False
numpy_docstring = numpy_func.__doc__
return numpy_docstring in docstring
def format_names(names):
return "\n".join(f" - {name}" for name in names)
namespaces = {
"xarray": xr,
"xarray.DataArray": xr.DataArray,
"xarray.Dataset": xr.Dataset,
}
funcs = dict(
itertools.chain.from_iterable(
public_api(namespace, base_name=name).items()
for name, namespace in namespaces.items()
)
)
docstrings = {name: func.__doc__ for name, func in funcs.items()}
without_docstring = tuple(
name
for name, docstring in docstrings.items()
if docstring is None or not docstring.strip()
)
filtered_docstrings = tuple(
(name, docstring)
for name, docstring in docstrings.items()
if (
docstring is not None
and not has_section(docstring, name="Examples")
and not is_dict_method(name)
)
)
without_examples_xarray = tuple(
name
for name, docstring in filtered_docstrings
if not is_numpy_wrapper(name, docstring)
)
without_examples_numpy = tuple(
name for name, docstring in filtered_docstrings if is_numpy_wrapper(name, docstring)
)
print(
f"functions without examples ({len(without_examples_xarray)}):",
format_names(without_examples_xarray),
sep="\n",
)
print()
print(
f"numpy wrappers without examples ({len(without_examples_numpy)}):",
format_names(without_examples_numpy),
sep="\n",
)
print()
print(
f"functions without docstring ({len(without_docstring)}):",
format_names(without_docstring),
sep="\n",
)analysis report in current main (with coarse filtering of advanced / deprecated API)For some of those it might be difficult to write examples for (i.e. the I/O methods / functions), and modifying the docstring of the numpy wrappers would require some refactoring. Most of the remaining ones are pretty easy to figure out and write examples for, however. If we remove the entry barrier as much as possible maybe these can be good first PRs with high impact? I'm not really sure how to do that, though... I'd try to group them by difficulty and create sub-issues with a check list for each group (so they're easy to find), and maybe also explain what a good example looks like or link to a appropriate explanation. The latter might be a good thing to add to the contributor's guide, too. |
42 tasks
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Noting down a comment by @danjonesocean on Twitter: https://twitter.com/DanJonesOcean/status/1441392596362874882
Our API docs are generated by the function docstrings, and these are usually the first thing users hit when they search for functions. However, these docstring uniformly lack examples, often leaving users stuck.
I see two ways to mitigate this:
The text was updated successfully, but these errors were encountered: