issues: 679575175

This data as json

id node_id number title user state locked assignee milestone comments created_at updated_at closed_at author_association active_lock_reason draft pull_request body reactions performed_via_github_app state_reason repo type
679575175 MDU6SXNzdWU2Nzk1NzUxNzU= 4345 Improve Dataset documentation 14371165 closed 0     9 2020-08-15T13:27:33Z 2020-10-27T19:47:51Z 2020-10-27T19:47:51Z MEMBER      

Is your feature request related to a problem? Please describe. As a new user I find it difficult to get a new dataset initialized because the necessary parameters are not shown in the docstring. I have to google "xarray dataset" to get to http://xarray.pydata.org/en/stable/generated/xarray.Dataset.html to figure it out.

In the figure below xarray.Dataset does not show the necessary parameters in the help pane:

Compare to pandas.DataFrame that includes it:

Describe the solution you'd like Looking at https://github.com/pydata/xarray/blob/master/xarray/core/dataset.py#L428 the xr.Dataset.__init__.__doc__ does contain the necessary parameters so the suggestion is to simply move or copy that information up one level toxr.Dataset.__doc__

For reference pandas does not use a docstring for the init method: https://github.com/pandas-dev/pandas/blob/v1.1.0/pandas/core/frame.py#L339-L9257

The pandas docs also includes a few simple copy/pasteable examples on how to initialize. So a xarray example would be: ```python

import numpy as np import xarray as xr x = np.arange(4) y = 2*x ds = xr.Dataset({'y': (['x'], y)}, ... coords={'x': x}) print(ds) <xarray.Dataset> Dimensions: (x: 4) Coordinates: * x (x) int32 0 1 2 3 Data variables: y (x) int32 0 2 4 6 ``` Or take some examples from http://xarray.pydata.org/en/stable/quick-overview.html#datasets or http://xarray.pydata.org/en/stable/data-structures.html#dataset although I found those a little bit confusing as they were dependent on previous results or rather complex with many dimensions.

Environment:

Output of <tt>xr.show_versions()</tt> INSTALLED VERSIONS ------------------ commit: None python: 3.7.7 (default, May 6 2020, 11:45:54) [MSC v.1916 64 bit (AMD64)] python-bits: 64 OS: Windows OS-release: 10 machine: AMD64 processor: Intel64 Family 6 Model 58 Stepping 9, GenuineIntel byteorder: little LC_ALL: None LANG: en LOCALE: None.None libhdf5: 1.10.4 libnetcdf: None xarray: 0.15.0 pandas: 1.0.3 numpy: 1.18.1 scipy: 1.4.1 netCDF4: None pydap: None h5netcdf: None h5py: 2.10.0 Nio: None zarr: None cftime: None nc_time_axis: None PseudoNetCDF: None rasterio: None cfgrib: None iris: None bottleneck: 1.3.2 dask: 2.14.0 distributed: 2.22.0 matplotlib: 3.1.3 cartopy: None seaborn: 0.10.0 numbagg: None setuptools: 49.2.1.post20200807 pip: 20.2.1 conda: 4.8.3 pytest: 6.0.1 IPython: 7.17.0 sphinx: 3.2.0 C:\ProgramData\Anaconda3\lib\site-packages\setuptools\distutils_patch.py:26: UserWarning: Distutils was imported before Setuptools. This usage is discouraged and may exhibit undesirable behaviors or errors. Please use Setuptools' objects directly or at least import Setuptools first. "Distutils was imported before Setuptools. This usage is discouraged " 
{
    "url": "https://api.github.com/repos/pydata/xarray/issues/4345/reactions",
    "total_count": 0,
    "+1": 0,
    "-1": 0,
    "laugh": 0,
    "hooray": 0,
    "confused": 0,
    "heart": 0,
    "rocket": 0,
    "eyes": 0
}
   completed 13221727 issue

Links from other tables