Repository: pandas-dev/pandas

Issue:
DOC: update the pandas.Series.dt.is_month_start docstring
Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

- [ X] PR title is "DOC: update the <your-function-or-method> docstring"
- [ X] The validation script passes: `scripts/validate_docstrings.py <your-function-or-method>`
- [ X] The PEP8 style check passes: `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [ X] The html version looks good: `python doc/make.py --single <your-function-or-method>`
- [X] It has been proofread on language by another sprint participant

Please include the output of the validation script below between the "```" ticks:

```
################################################################################
################# Docstring (pandas.Series.dt.is_month_start)  #################
################################################################################

Return a boolean indicating if the date is the first day of the month.

Returns
-------
is_month_start : Series of boolean

See Also
--------
is_month_end : Returns a boolean indicating if the date is the last day of the month.

Examples
--------
>>> import pandas as pd
>>> dates = pd.Series(pd.date_range("2018-02-27", periods = 3))
>>> dates
0   2018-02-27
1   2018-02-28
2   2018-03-01
dtype: datetime64[ns]
>>> dates.dt.is_month_start
0    False
1    False
2    True
dtype: bool

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
	No extended summary found
```

If the validation script still gives errors, but you think there is a good reason
to deviate in this case (and there are certainly such cases), please state this
explicitly.

This function does not require an extended summary. Peers find it very clear with a short summary too.


Discussion:
Hello @janelle! Thanks for updating the PR.

 - In the file [`pandas/core/indexes/datetimes.py`](https://github.com/pandas-dev/pandas/blob/5227cad133e2ccb31330d38dc5910dd723fa3be6/pandas/core/indexes/datetimes.py), following are the PEP8 issues :

> [Line 1731:80](https://github.com/pandas-dev/pandas/blob/5227cad133e2ccb31330d38dc5910dd723fa3be6/pandas/core/indexes/datetimes.py#L1731): [E501](https://duckduckgo.com/?q=pep8%20E501) line too long (83 > 79 characters)



##### Comment last updated on March 10, 2018 at 15:01 Hours UTC
thanks for reviewing, adjusted line lengths and writing style now.
@arnau126 adjusted line lengths and writing style
This PR is perhaps no longer relevant, the _field_accessor(...) transform was replaced by the _wrap_field_accessor(name) in [this commit](https://github.com/pandas-dev/pandas/commit/30eb48cc485bb7c7c47a4e7e26f87e469fbd8b8a) @datapythonista 
@CalmDownKarm the function has been moved here:
- https://github.com/pandas-dev/pandas/blob/master/pandas/core/arrays/datetimes.py#L945

I think the best would be to start a fresh branch from master, and copy the code from the docstring in this PR to that location.

CC: @jbrockmendel 

Resolving patch:
diff --git a/pandas/core/arrays/datetimes.py b/pandas/core/arrays/datetimes.py
--- a/pandas/core/arrays/datetimes.py
+++ b/pandas/core/arrays/datetimes.py
@@ -998,48 +998,60 @@ def date(self):
         'dim',
         "The number of days in the month")
     daysinmonth = days_in_month
-    is_month_start = _field_accessor(
-        'is_month_start',
-        'is_month_start',
-        "Logical indicating if first day of month (defined by frequency)")
-    is_month_end = _field_accessor(
-        'is_month_end',
-        'is_month_end',
-        """
-        Indicator for whether the date is the last day of the month.
+    _is_month_doc = """
+        Indicates whether the date is the {first_or_last} day of the month.
 
         Returns
         -------
         Series or array
-            For Series, returns a Series with boolean values. For
-            DatetimeIndex, returns a boolean array.
+            For Series, returns a Series with boolean values.
+            For DatetimeIndex, returns a boolean array.
 
         See Also
         --------
-        is_month_start : Indicator for whether the date is the first day
-            of the month.
+        is_month_start : Return a boolean indicating whether the date
+            is the first day of the month.
+        is_month_end : Return a boolean indicating whether the date
+            is the last day of the month.
 
         Examples
         --------
         This method is available on Series with datetime values under
         the ``.dt`` accessor, and directly on DatetimeIndex.
 
-        >>> dates = pd.Series(pd.date_range("2018-02-27", periods=3))
-        >>> dates
+        >>> s = pd.Series(pd.date_range("2018-02-27", periods=3))
+        >>> s
         0   2018-02-27
         1   2018-02-28
         2   2018-03-01
         dtype: datetime64[ns]
-        >>> dates.dt.is_month_end
+        >>> s.dt.is_month_start
+        0    False
+        1    False
+        2    True
+        dtype: bool
+        >>> s.dt.is_month_end
         0    False
         1    True
         2    False
         dtype: bool
 
         >>> idx = pd.date_range("2018-02-27", periods=3)
+        >>> idx.is_month_start
+        array([False, False, True])
         >>> idx.is_month_end
-        array([False,  True, False], dtype=bool)
-        """)
+        array([False, True, False])
+    """
+    is_month_start = _field_accessor(
+        'is_month_start',
+        'is_month_start',
+        _is_month_doc.format(first_or_last='first'))
+
+    is_month_end = _field_accessor(
+        'is_month_end',
+        'is_month_end',
+        _is_month_doc.format(first_or_last='last'))
+
     is_quarter_start = _field_accessor(
         'is_quarter_start',
         'is_quarter_start',


Test patch: