doc: add docstring for discovery method

The information is mainly copied from OpenAPI page, with numpy docstring style applied.
All the doctests are disabled. I will add a separate file for them so they are not outdated.