DOC: Adding guide for the pandas documentation sprint
State: closed

This PR is to make it easier to review the proposal guide for the pandas documentation sprint, as discussed in pandas-dev.


Labels:
name: Docs

Comments:
Apart from my one comment, I think this is great and appreciate what you've done to pull it together!
BTW, we should certainly keep this as a separate document, the contributing.rst is already long enough (we should rather start splitting more of our long doc pages in separate pieces IMO)
All comments should be addressed in this new version, except in the cases where I added a comment to the review. And also, it's pending the part on the standard datasets (#19710).
@jorisvandenbossche, here you have the list of all parameters currently used in docstrings:

<details>

``` list of columns, or True, default None
 {'any', 'all'}, default 'any'
'all', list-like of dtypes or None (default), optional
'fixed(f)|table(t)', default is 'fixed'
'infer', bool-ndarray, 'NaT', default 'raise'
'raise', 'coerce', default 'raise'
(float,float), optional
1d array-like
1d ndarray or Series
2-length sequence (tuple, list, ...)
A tuple (width, height) in inches
CategoricalDtype
DataFrame
DataFrame or Panel
DataFrame or Series
DataFrame or Series/dict-like object, or list of these
DataFrame, Series
DataFrame, Series with name field set, or list of DataFrame
DataFrame, or object coercible into a DataFrame
DateOffset object, or string
DateOffset, timedelta, or offset alias string, optional
DateOffset, timedelta, or time rule string, default None
DateOffset, timedelta, or time rule string, optional
DatetimeIndex or TimedeltaIndex
Drop groups that do not pass the filter. True by default;
Grouped DataFrame
How to join individual DataFrames
Index
Index or array-like
Index or list/tuple of indices
Index, optional
Index-like
Index-like (unique), optional
IndexSlice
Keyword Arguments
Matplotlib axes object, optional
Matplotlib axis object, default None
Matplotlib axis object, optional
MultiIndex or list of tuples
NDFrame, default None
Name of the column containing class names
None
None or float value, default None
None or float value, default None (NaN)
None or str, optional
None, integer or string axis name, optional
NumPy array or integer, optional
NumPy dtype (default: float64)
NumPy dtype (default: int64)
NumPy dtype (default: object)
NumPy dtype (default: uint64)
Number of points to plot in each curve
Object
Panel or list of Panels
Panel, or object coercible to Panel
Period frequency
Period or compat.string_types, default None
Python write mode, default 'w'
SQLAlchemy connectable (engine/connection) or database string URI
SQLAlchemy engine or DBAPI2 connection (legacy mode)
Series
Series or DataFrame
Series or list/tuple of Series
Series or scalar value
Series, DataFrame
Series, DataFrame, or constant
Series, DataFrame, or ndarray, optional
Setting this to True will show the grid
StringIO-like, optional
The number of decimal places to use when encoding
The object to check.
Timedelta, timedelta, np.timedelta64, string, or integer
Type name or dict of column -> type, default None
a list of columns that if not None, will limit the return
a sequence or mapping of Series, DataFrame, or Panel objects
a valid JSON string or file-like, default: None
alignment axis if needed, default None
alignment level if needed, default None
allowed axis of the other object, default None
an iterable
array or boolean, default None
array-like
array-like (1-dimensional)
array-like (1-dimensional), optional
array-like or Categorical, (1-dimensional)
array-like or Index (1d)
array-like or callable, default None
array-like, Series, or DataFrame
array-like, Series, or list of arrays/Series
array-like, default None
array-like, dict, or scalar value
array-like, integers
array-like, optional
array-like, optional (should be specified using keywords)
array_like
axes to direct sorting
axis to shift, default 0
bool
bool (default True)
bool (default: True)
bool or None, default True
bool or list of bool, default True
bool or same types as ``to_replace``, default False
bool, default False
bool, default NaN
bool, default None
bool, default True
bool, default True.
bool, defaults to False
bool, optional
boolean
boolean (default: False)
boolean NDFrame, array-like, or callable
boolean array-like with the same length as self
boolean or dict, default True
boolean or list of ints or names or list of lists or dict, default False
boolean or list of string, default True
boolean or string, default False
boolean or string, default True
boolean whether to append to an existing msgpack
boolean,
boolean, (default False)
boolean, True by default
boolean, default False
boolean, default False, do not write an ALL nan row to
boolean, default None
boolean, default True
boolean, default True if ax is None else False
boolean, default True, append the input data to the
boolean, default ``True``
boolean, default is True,
boolean, default to False
boolean, defaults to False
boolean, defaults to True
boolean, if True, return an iterator to the unpacker
boolean, optional
boolean, return an iterator, default False
boolean, should automatically close the store when
boolean, {'all', 'index', 'columns'}, or {0,1}, default False
boolean/string, default None
callable
callable or tuple of (callable, string)
callable(1d-array) -> 1d-array<boolean>, default None
callable, default None
callable, optional
callable, string, dictionary, or list of string/callables
category or list of categories
category or list-like of category
character, default ","
class, default dict
closed end of interval; 'left' or 'right'
column label or list of column labels / arrays
column label or sequence of labels, optional
column name or list of names, or vector
column to aggregate, optional
column, Grouper, array, or list of the previous
data type, or dict of column name -> data type
date or array of dates
date, string, int
datetime
datetime-like, str, int, float
datetime.time or string
datetime.time, str
default NaN, fill value for missing values.
default None, provide an encoding for strings
deprecated, use `expand`
dict
dict (python 3), str or None (python 2)
dict of column name to SQL type, default None
dict of columns that specify minimum string sizes
dict or list of dicts
dict, default None
dict, default is None
dict, optional
dict-like or function, optional
dtype or None, default None
dtype, default None
dtype, default np.uint8
end time, datetime-like, optional
end time, timedelta-like, optional
end value, period-like, optional
expected TOTAL row size of this table
float
float or array-like, default 0.5 (50% quantile)
float or array_like
float or array_like, default None
float, default NaN
float, default None
float, defaults to NaN (missing)
float, optional
force encoded string to be ASCII, default True.
freq string/object
frequency string
function
function, default None
function, dict, or Series
function, list of functions, dict, default numpy.mean
function, optional
hint to the hashtable sizer
identifier of index column, defaults to None
ignored
index to direct sorting
index, columns to direct sorting
index-like
int
int (can only be zero)
int (default: 0)
int (default: 0), or other RangeIndex instance.
int (default: 1)
int or None
int or array
int or axis name
int or basestring
int or csv.QUOTE_* instance, default 0
int or level name or list of ints or list of level names
int or level name, default None
int or list of ints
int or list of ints, default 'infer'
int or list, default None
int or name
int or numpy.random.RandomState, optional
int or sequence or False, default None
int or str
int or str, default 0
int or str, optional
int or str, optional, default None
int or string
int or string axis name
int or string axis name, optional
int or string, default 0
int or string, optional
int, Series, or array-like
int, array, or Series, default None
int, array-like
int, default -1
int, default -1 (all)
int, default 0
int, default 0 (no flags)
int, default 1
int, default 5
int, default None
int, default None.
int, defaults None
int, dict, Series
int, float, Interval
int, level name, or sequence of int/level names (default None)
int, level name, or sequence of such, default None
int, list of ints, default 0
int, list of ints, default None
int, optional
int, optional, > 0
int, optional, default 0
int, or offset
int, sequence of scalars, or IntervalIndex
int, str or None
int, str, default None
int, str, tuple, or list, default None
int, string (can be mixed)
int, string, or list of these, default -1 (last level)
int, string, or list of these, default last level
int/level name or list thereof
integer (defaults to None), row number to start selection
integer (defaults to None), row number to stop selection
integer or array of quantiles
integer or sequence, default 10
integer, default 1
integer, default None
integer, float, string, datetime, list, tuple, 1-d array, Series
integer, optional
interval boundary to use for labeling; 'left' or 'right'
item label (panel item)
iterable, Series, DataFrame or dictionary
iterable, optional
keyword arguments to pass on to the constructor
keyword arguments to pass on to the interpolating function.
keyword, value pairs
keywords
label
label or list
label or list, or array-like
label or position, optional
label or tuple of labels (one for each level)
label rotation angle
label, default None
list
list / sequence of array-likes
list / sequence of iterables
list / sequence of strings or None
list / sequence of tuple-likes
list of Index objects
list of Term (or convertible) objects, optional
list of columns to create as data columns, or True to
list of int or list of str
list of int representing new level order.
list of ints. optional
list of pairs (int, int) or 'infer'. optional
list of paths (string or list of strings), default None
list of sequences, default None
list or None
list or dict of one-parameter functions, optional
list or dict, default: None
list, default None
list, default: None
list, tuple or dict, optional, default: None
list, tuple, 1-d array, or Series
list-like
list-like of Categorical, CategoricalIndex,
list-like of dtypes or None (default), optional,
list-like of numbers, optional
list-like or None, default None
list-like or integer or callable, default None
list-like, default None
list-like, dict-like or callable
list-like, int or str, default 0
list-like, or list of list-likes
mapping, function, label, or list of labels
mapping, optional
matplotlib axes object, default None
matplotlib axis object
name, tuple/list of names, or array-like
name/number, defaults to None
ndarray
ndarray (1-d)
ndarray (items x major x minor), or dict of DataFrames
ndarray (structured dtype), list of tuples, dict, or DataFrame
ndarray or object value
nrows to include in iteration, return an iterator
number/name of the axis, defaults to 0
numeric or datetime-like, default None
numeric, optional
numeric, string, or DateOffset, default None
numpy dtype or pandas type
numpy ndarray (structured or homogeneous), dict, or DataFrame
numpy.dtype or None
object
object to be converted
object, default ''
object, default None
object, defaults to first n levels (n=1 or len(key))
object, optional
one-parameter function, optional
optional
optional int
optional sequence of objects
optional, 'infer' or None, defaults to None
optional, array-like
optional, defaults False.
optional, defaults to tab
other plotting keyword arguments
path (string), buffer or path object (pathlib.Path or
pytz.timezone or dateutil.tz.tzfile
raise on invalid input
replace NaN with this value if the unstack produces
scalar
scalar or array_like, optional
scalar or list-like
scalar value
scalar, NDFrame, or callable
scalar, default 'value'
scalar, default None
scalar, default is 'unix'
scalar, default np.NaN
scalar, dict, Series, or DataFrame
scalar, dict, list, str, regex, default None
scalar, hashable sequence, dict-like or function, optional
scalar, list-like, dict-like or function, optional
scalar, list-like, optional
scalar, or array-like
scalar, str, list-like, or dict, default None
scipy.sparse.coo_matrix
sequence
sequence of (key, value) pairs
sequence of arrays
sequence or list of sequence
sequence, default None
sequence, optional
set or list-like
single label or list-like
size to chunk the writing
sort by the remaining levels after level.
starting value, datetime-like, optional
starting value, period-like, optional
starting value, timedelta-like, optional
str
str (length 1), default None
str (length 1), optional
str or None
str or PeriodDtype, default None
str or buffer
str or csv.Dialect instance, default None
str or file-like
str or int, optional
str or list
str or list of str
str or list-like
str or matplotlib colormap object, default None
str or ndarray-like, optional
str or sequence
str or unicode
str {'E', 'S'}
str {'dict', 'list', 'series', 'split', 'records', 'index'}
str, default ""
str, default ','
str, default '.'
str, default '\\d+'
str, default '\s+'.
str, default 'pad'
str, default None
str, default \t (tab-stop)
str, default ``'	' + ' '``
str, default ``None``
str, default is 'utf-8'
str, method of resampling ('ffill', 'bfill')
str, optional
str, optional (python 2)
str, pathlib.Path, py._path.local.LocalPath or any \
str, regex, list, dict, Series, numeric, or None
str, tuple, datetime.timedelta, DateOffset or None
str, {'raise', 'ignore'}, default 'raise'
string
string (regular expression)
string / frequency object, defaults to None
string File path, BytesIO like or string
string File path, buffer-like, or None
string SQL query or SQLAlchemy Selectable (select or text object)
string file path or file handle / StringIO
string file path, or file-like object
string or DateOffset, default 'B' (business daily)
string or DateOffset, default 'D' (calendar daily)
string or DateOffset, optional
string or ExcelWriter object
string or None
string or None, default None
string or SQLAlchemy Selectable (select or text object)
string or callable
string or compiled regex
string or datetime-like, default None
string or file handle, default None
string or file-like object
string or int, optional
string or list of strings, default None
string or list of strings, optional, default: None
string or object
string or object, optional
string or pandas offset object, optional
string or period object, optional
string or period-like, default None
string or pytz.timezone object
string or sequence
string or sequence, default None
string or timedelta-like, default None
string to use as string nan represenation
string {'xport', 'sas7bdat'} or None
string,
string, DateOffset, dateutil.relativedelta
string, None or encoding
string, default
string, default "Pandas"
string, default "|"
string, default ''
string, default '.'
string, default 'All'
string, default 'Sheet1'
string, default '_'
string, default 'inf'
string, default 'ms' (milliseconds)
string, default 'ns'
string, default None
string, default frequency of PeriodIndex
string, default is None
string, default whitespace
string, defaults to None
string, int, mixed list of strings/ints, or None, default 0
string, list of fields, array-like
string, list of strings, or dict of strings, default None
string, number, or hashable object
string, optional
string, optional, default: None
string, optional, {'pad', 'ffill', 'bfill'}
string, path object (pathlib.Path or py._path.local.LocalPath),
string, pytz.timezone, dateutil.tz.tzfile or None
string, timedelta, list, tuple, 1-d array, or Series
string, valid regular expression
string, {'ns', 'us', 'ms', 's', 'm', 'h', 'D'}, optional
the axis to convert
the axis to localize
the pandas object holding the data
the path (string) or HDFStore object
the path or buffer to write the result string
three positional arguments: each one of
timedelta
tuple
tuple (optional)
tuple and dict
tuple of integer (length 2), default None
tuple, default None
tuple, list, or ndarray, optional
tuple, optional
tuple/list
type of compressor (zlib or blosc), default to None (no
type of object to recover (series or frame), default 'frame'
unit of the arg (D,h,m,s,ms,us,ns) denote the unit, which is an
value
where to reorder levels
writable buffer, defaults to sys.stdout
{'NFC', 'NFKC', 'NFD', 'NFKD'}
{'all', 'any'}, default 'any'
{'any', 'all'}
{'auto', 'pyarrow', 'fastparquet'}, default 'auto'
{'average', 'min', 'max', 'first', 'dense'}
{'average', 'min', 'max', 'first', 'dense'}, efault 'average'
{'backfill', 'bfill', 'pad', 'ffill', None}, default None
{'backfill'/'bfill', 'pad'/'ffill'}, default None
{'block', 'integer'}
{'c', 'python'}, optional
{'columns', 'index'}, default 'columns'
{'fail', 'replace', 'append'}, default 'fail'
{'first', 'last', False}, default 'first'
{'first', 'last'}, default 'first'
{'first', 'last'}, default 'last'
{'forward', 'backward', 'both'}, default 'forward'
{'hist', 'kde'}
{'ignore', 'raise', 'coerce'}, default 'raise'
{'ignore', 'raise'}, default 'raise'
{'infer', 'gzip', 'bz2', 'xz', 'zip', None}, default 'infer'
{'infer', 'gzip', 'bz2', 'xz', None}, default 'infer'
{'infer', 'gzip', 'bz2', 'zip', 'xz', None}, default 'infer'
{'inner', 'outer'}, default 'outer'
{'inside', 'outside'}, default None
{'integer', 'signed', 'unsigned', 'float'} , default None
{'items', 'major', 'minor'}
{'items', 'major', 'minor'} or {0, 1, 2}
{'items', 'major', 'minor}, default 1/'major'
{'items', 'minor', 'major'}, or {0, 1, 2}, or a tuple with two
{'items', 'minor'}, default 'items'
{'ix', 'loc', 'getitem'}
{'ix', 'loc', 'getitem'} or None
{'keep', 'top', 'bottom'}
{'left', 'right', 'both', 'neither'}, default 'right'
{'left', 'right', 'both'}, default 'left'
{'left', 'right', 'inner', 'outer'}
{'left', 'right', 'outer', 'inner'}
{'left', 'right', 'outer', 'inner'}, default 'inner'
{'left', 'right', 'outer', 'inner'}, default: 'left'
{'left', 'right'}
{'left', 'zero',' mid'}, default 'left'
{'left'}, default 'left'
{'linear', 'lower', 'higher', 'midpoint', 'nearest'}
{'linear', 'time', 'index', 'values', 'nearest', 'zero',
{'major', 'minor', 'items'}, default 'major'
{'mergesort', 'quicksort', 'heapsort'}, default 'quicksort'
{'outer', 'inner', 'left', 'right'}, default 'outer'
{'pearson', 'kendall', 'spearman'}
{'quicksort', 'mergesort', 'heapsort'}, default 'quicksort'
{'raise', 'ignore'}, default 'raise'
{'raise', 'ignore'}, default 'raise'.
{'right', 'left'}
{'s', 'e', 'start', 'end'}
{'snappy', 'gzip', 'brotli', None}, default 'snappy'
{'start', 'end', 'e', 's'}
{'start', 'end', 's', 'e'}
{'start', 'end'}, default end
{0 or 'index', 1 or 'columns'}
{0 or 'index', 1 or 'columns'}, default 0
{0 or 'index', 1 or 'columns'}, default None
{0 or 'index', 1 or 'columns'}, or tuple/list thereof
{0, 'index'}
{0, 'index'}, default 0
{0, 'index'}, default None
{0, 1, 'index', 'columns'}
{0, 1, 'index', 'columns'} (default 0)
{0, 1}, default 0
{0/'index', 1/'columns'}, default 0
{None, 'axes', 'dict', 'both'}, default None
{None, 'backfill'/'bfill', 'pad'/'ffill', 'nearest'}, optional
{None, 'epoch', 'iso'}
{None, 'gzip', 'bz2', 'xz'}
{None, 'ignore'}
{None, 'pad'/'ffill', 'backfill'/'bfill', 'nearest'}, optional
{None, True, False}, optional
{Series, DataFrame, Panel}
{default 'raise', 'drop'}, optional
{index (0), columns (1)}
{index (0)}
{items (0), major_axis (1), minor_axis (2)}
{items, major_axis, minor_axis}
```

</details>
Where's this at? Are we going through another round of reviews or can we merge this and iterate if needed?
@TomAugspurger I made some changes based on the points discussed in pandas-dev in the python-sprints version:
https://github.com/python-sprints/python-sprints.github.io/commit/0dc3c18f6d0daffc398948e7009fd405e70d8441

I need to address couple of comments that @jorisvandenbossche pointed out (the default is incorrectly defined, the fillna is not good...) and then should be a good first version. I'll make the changes later today and update this PR with them.
I copied the latest version of the sprints repo, and pushed that as a commit.So people can already give this another round of review here if needed.
Updated the documentation with the last changes (mainly the points discussed in pandas-dev), and two new sections, one at the beginning about when to use backticks in the docstrings, and another at the end on how to add plots to the documentation.

Any feedback welcome. If you prefer to read it in html, the exact same version as this PR is available here: https://python-sprints.github.io/pandas/guide/pandas_docstring.html
@datapythonista thanks a lot for the updates. Really looking great.

At the others, if you could do a final read of it before the sprint, that would be very welcome.
Yes, without. Not a big deal though.

On Fri, Mar 9, 2018 at 11:31 AM, Joris Van den Bossche <
notifications@github.com> wrote:

> *@jorisvandenbossche* commented on this pull request.
> ------------------------------
>
> In doc/source/contributing_docstring.rst
> <https://github.com/pandas-dev/pandas/pull/19704#discussion_r173515711>:
>
> > +- {'simple', 'advanced'}
> +- {'low', 'medium', 'high'}
> +- {'cat', 'dog', 'bird'}
> +
> +If the type is defined in a Python module, the module must be specified:
> +
> +- datetime.date
> +- datetime.datetime
> +- decimal.Decimal
> +
> +If the type is in a package, the module must be also specified:
> +
> +- numpy.ndarray
> +- scipy.sparse.coo_matrix
> +
> +If the type is a pandas type, also specify pandas except for Series and
>
> Do you mean everything with 'pandas', or everything without it?
> I suppose without? I am fine with that, I think it was added mainly for
> being explicit for objects that maybe not everybody knows are coming from
> pandas.
>
> —
> You are receiving this because you were mentioned.
> Reply to this email directly, view it on GitHub
> <https://github.com/pandas-dev/pandas/pull/19704#discussion_r173515711>,
> or mute the thread
> <https://github.com/notifications/unsubscribe-auth/ABQHItBCAf3M2f_qXiogDyHdl5bqCfpGks5tcryDgaJpZM4SGDCd>
> .
>

Un up to date version is hosted on the sprint website, so merging is not that urgent. But also no problem to merge
Ah, OK. does it make sense to include the shared doc guide from
https://github.com/pandas-dev/pandas/pull/20016 in the version on the
sprint website?

On Fri, Mar 9, 2018 at 2:17 PM, Joris Van den Bossche <
notifications@github.com> wrote:

> Un up to date version is hosted on the sprint website, so merging is not
> that urgent. But also no problem to merge
>
> —
> You are receiving this because you were mentioned.
> Reply to this email directly, view it on GitHub
> <https://github.com/pandas-dev/pandas/pull/19704#issuecomment-371933508>,
> or mute the thread
> <https://github.com/notifications/unsubscribe-auth/ABQHIopshw72kAS5t0PhwpcObcHh5DBQks5tcuM8gaJpZM4SGDCd>
> .
>

@TomAugspurger yeah, if you would have time for that, that would be welcome
OK, I updated it with the latest version from the sprint website and merged this ones, I will create another issue to discuss further needed clarifications.
Opened issue here: https://github.com/pandas-dev/pandas/issues/20309