Standardize docstrings for table-like inputs #1186
Conversation
The virtualfile_from_data function wrapped in #961 allows for a standardized way for inputting data to PyGMT modules. This change is for standardizing some of the docstrings, specifically for 'table-like' vector inputs which can be of several different PyData object types.
There was a problem hiding this comment.
Would it be worth standardizing the description that accompanies {table-like} in each parameter? e.i., "a 1D/2D :class:numpy.ndarray, a :class:pandas.DataFrame, or an :class:xarray.Dataset made up of 1D :class:xarray.DataArray data variables containing the tabular data."
Yes I did think of adding a standard
|
Co-Authored-By: Meghan Jones <[email protected]>
If there were a Would you prefer to wait on the last three methods or get a final review on this now to merge? It will be at least a few days before I get to the blockm* refactoring. |
Hmm, you're right. I'll update things to use a standard {table-description}, will take me an hour or so after lunch. Edit: done in 44f941b.
I think we can do the last three methods next time. Prefer to get this PR in so that I can finalize the geopandas integration PR at #1000. But I'll do the {table-description} issue above ☝️ first. |
Co-authored-by: Meghan Jones <[email protected]>
Also had to remove curly brackets from doctest so that they are not treated as placeholders to be substituted.
Co-Authored-By: Dongdong Tian <[email protected]>
The virtualfile_from_data function wrapped in GenericMappingTools#961 allows for a standardized way for inputting data to PyGMT modules. This change is for standardizing some of the docstrings, specifically for 'table-like' vector inputs which can be of several different PyData object types. * Reformat pygmt.info docstring to use table-like filler * Reformat plot and plot3d docstring to use table-like filler * Reformat data_kind and virtualfile_from_data docstring to use table-like filler * Reformat rose docstring to use table-like filler * Reformat grdtrack docstring to use table-like filler * Reformat velo docstring to use table-like filler * Reformat wiggle docstring to use table-like filler * Reformat histogram docstring to use table-like filler * Add Python list to histogram's table param description * Use table-classes filler in docstring description * Use fmt_docstring decorator on virtualfile_from_data function Also had to remove curly brackets from doctest so that they are not treated as placeholders to be substituted. * Add a doctest for the table-classes filler text Co-authored-by: Meghan Jones <[email protected]> Co-authored-by: Dongdong Tian <[email protected]>
Description of proposed changes
The virtualfile_from_data function wrapped in #961 allows for a standardized way for inputting data to PyGMT modules. This change is for standardizing some of the docstrings, specifically for modules that accept 'table-like' vector inputs. The inputs can be of several different PyData object types.
Plus there will likely be more data type objects wrapped in the future, so it will be good to have a standardized place for them.
TODO:
Addresses #1000 (comment)
Reminders
make formatandmake checkto make sure the code follows the style guide.doc/api/index.rst.Slash Commands
You can write slash commands (
/command) in the first line of a comment to performspecific operations. Supported slash commands are:
/format: automatically format and lint the code/test-gmt-dev: run full tests on the latest GMT development version