DOC: in docstrings point users to valid offset aliases

[patricktokeeffe]

Many timeseries-related functions have a freq argument that accepts strings representing some offset value. The specific valid options are apparently known as "offset aliases." Not exactly intuitive search terms but I did eventually find https://github.com/pydata/pandas/blob/master/doc/source/timeseries.rst which lists the valid aliases.

I can understand why it's suboptimal to list all valid aliases in the docstring of every function with a freq argument but it's also frustrating for users to be told "use one of these" without being told what "these" are. Can a balance be struck?

Perhaps the aliases are already defined in some docstring and I have not found them. In this case, adding a "see here for valid aliases" would probably be sufficient. If they are not, however, what would be the best way of incorporating them?

[ghost]

One option would be to to add some kind of .apropos(topic) method to pandas, and naming
the relavent topic in the docstring. putting long tables directly into docstrings is a duplication
that makes maintenance hard.

Another way to go is to use docstring templates, already there in some places, but
that "one-size-fits-a-family" solution also came up short in at least one issue I can't
locate right now.

If you can produce a laundry list of docstrings to fix, that'd be a good start on fixing this
for 0.12. I've been considering a doctsring overhaul for 0.12 already.

[patricktokeeffe]

I won't make promises but I'd like to contribute and I can handle docstrings.

Would it be too hackish to define all the aliases in a triple-quoted string inside the appropriate module (maybe pd.tseries.offsets?) then string-substitute into the docstrings that require it? Other modules could import just that triple-quoted string. Updating the """ string would propogate changes automatically.

[ghost]

Take a look at the Appender class in pands/util/decorators.py,
uses in various places in the code for that purpose.

[jreback]

@patricktokeeffe able to contribute to this?

[patricktokeeffe]

@jreback It looks like the Appender class is the tool of choice. I have the text to insert ready but Appender chokes on classes so I haven't gotten very far yet.

patricktokeeffe@1fa2453 I edited the docstrings of all the "public" offset classes listed in __all__ so the first (summary) line could be parsed off and used to build the table displayed below. The first column is from the names in __all__ and the second column is the docstring summary.

>>> import pandas
>>> print pandas.tseries.offsets._alias_doc
Offset Aliases
--------------
BDay               Business day (weekday)
BMonthBegin        Business month begin date
BMonthEnd          Business month end dates
BQuarterBegin      Business quarter begin date
BQuarterEnd        Business quarter end date
BYearBegin         Business year begin date
BYearEnd           Business year end date
BusinessDay        Business day (weekday)
CDay               Custom representation **EXPERIMENTAL**
CustomBusinessDay  Custom representation **EXPERIMENTAL**
Day                One calendar day
FY5253             End date, 52-53 week fiscal year (4-4-5 calendar)
FY5253Quarter      Quarter end, 52-53 week fiscal year (4-4-5 calendar)
Hour               One hour
LastWeekOfMonth    Dates like "last Tuesday of the month"
Micro              One microsecond
Milli              One millisecond
Minute             One minute
MonthBegin         Calendar month begin date
MonthEnd           Calendar month end date
Nano               One nanosecond
QuarterBegin       Calendar quarter begin date
QuarterEnd         Calendar quarter end date
Second             One second
Week               Week, optionally anchored on day of the week
WeekOfMonth        Dates like "Tuesday of the 2nd week each month"
YearBegin          Calendar year begin date
YearEnd            Calendar year end date
>>> 

[ghost]

Someone please put up a PR that points at the docs/wiki section in relavent docstrings for 0.14.0

[jreback]

@jorisvandenbossche any idea how to do this?

[linebp]

This appears to be related to #13160 and can also be marked as closed?

[jreback]

yep, thanks @linebp

of course if there are other doc-strings that appear to need to link, pls open a new issue listing them (of course PR is even better)!