DOC: greater consistency and spell-check for intro docs #18948

tommyod · 2017-12-26T16:14:47Z

I read through introductory docs, and made the following changes:

Added missing periods, which were sometimes absent in short sentences.
In other parts of the documentation, code examples appear to typically be introduced with a colon. This has been added in some sentences which introduce code and do not end in a period nor a colon.
Updated a reference to the Python 2 docs to Python 3.
Restructured a few sentences slightly.
Found an example of code that did not run due to an extra }, which I removed.

codecov · 2017-12-26T19:45:13Z

Codecov Report

Merging #18948 into master will decrease coverage by 0.02%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master   #18948      +/-   ##
==========================================
- Coverage   91.59%   91.57%   -0.03%     
==========================================
  Files         150      150              
  Lines       48959    48964       +5     
==========================================
- Hits        44845    44838       -7     
- Misses       4114     4126      +12

Flag	Coverage Δ
#multiple	`89.93% <ø> (-0.03%)`	⬇️
#single	`41.13% <ø> (ø)`	⬆️

Impacted Files	Coverage Δ
pandas/plotting/_converter.py	`65.22% <0%> (-1.74%)`	⬇️
pandas/core/groupby.py	`92.08% <0%> (ø)`	⬆️
pandas/core/resample.py	`96.36% <0%> (+0.01%)`	⬆️

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update ee9c7e9...e8cb0f3. Read the comment docs.

jreback

looks good. thanks! some comments, mainly would love to update to use references where we have not already, e.g. :meth:`DataFrame.apply` for example rather than apply.

jreback · 2017-12-26T21:32:41Z

doc/source/basics.rst

@@ -764,7 +764,7 @@ For example, we can fit a regression using statsmodels. Their API expects a form
 The pipe method is inspired by unix pipes and more recently dplyr_ and magrittr_, which
 have introduced the popular ``(%>%)`` (read pipe) operator for R_.
 The implementation of ``pipe`` here is quite clean and feels right at home in python.
-We encourage you to view the source code (``pd.DataFrame.pipe??`` in IPython).
+We encourage you to view the source code of ``pd.DataFrame.pipe``.


can you make this a func reference

jreback · 2017-12-26T21:33:01Z

doc/source/basics.rst

@@ -786,7 +786,7 @@ statistics methods, take an optional ``axis`` argument:
   df.apply(np.cumsum)
   df.apply(np.exp)

-``.apply()`` will also dispatch on a string method name.
+The ``.apply()`` method will also dispatch on a string method name.


can you make this a func reference (use DataFrame.apply is fine)

like on line 866

jreback · 2017-12-26T21:33:34Z

doc/source/basics.rst

@@ -1008,7 +1009,7 @@ function name or a user defined function.
   tsdf.transform('abs')
   tsdf.transform(lambda x: x.abs())

-Here ``.transform()`` received a single function; this is equivalent to a ufunc application
+Here ``.transform()`` received a single function; this is equivalent to a ufunc application.


can you add the refernce here

jreback · 2017-12-26T21:35:17Z

doc/source/basics.rst

@@ -1515,7 +1516,7 @@ To iterate over the rows of a DataFrame, you can use the following methods:
    over the values. See the docs on :ref:`function application <basics.apply>`.

  * If you need to do iterative manipulations on the values but performance is
-    important, consider writing the inner loop using e.g. cython or numba.
+    important, consider writing the inner loop using for instance cython or numba.


a comma before for instance

jreback · 2017-12-26T21:35:28Z

doc/source/basics.rst

@@ -1594,7 +1595,7 @@ index value along with a Series containing the data in each row:

   To preserve dtypes while iterating over the rows, it is better
   to use :meth:`~DataFrame.itertuples` which returns namedtuples of the values
-   and which is generally much faster as ``iterrows``.
+   and which is generally much faster than ``iterrows``.


can you add the reference

jreback · 2017-12-26T21:36:47Z

doc/source/overview.rst


 * A set of labeled array data structures, the primary of which are
-   Series and DataFrame
+   Series and DataFrame.


this same text exists in pandas/__init__.py can you update there as well.

jschendel · 2017-12-26T21:50:08Z

doc/source/10min.rst

@@ -425,7 +426,7 @@ String Methods
 Series is equipped with a set of string processing methods in the `str`
 attribute that make it easy to operate on each element of the array, as in the
 code snippet below. Note that pattern-matching in `str` generally uses `regular
-expressions <https://docs.python.org/2/library/re.html>`__ by default (and in
+expressions <https://docs.python.org/3.5/library/re.html>`__ by default (and in


Can you use /3/ instead of /3.5/? That way it should always link to the most recent version of Python 3.

tommyod · 2017-12-27T14:08:14Z

@jreback and @jschendel : I have made the requested changes.

jreback · 2017-12-27T19:30:39Z

thanks @tommyod

built docs are: http://pandas-docs.github.io/pandas-docs-travis/ (likely take a few hours). please make sure changes are rendered ok. thanks!

tommyod · 2017-12-27T19:44:16Z

@jreback - Great, will do. I hope to find the time to read more of the documentation and make similar changes if I see room for improvement, i.e. punctuation, function references, small changes to sentences, and so forth.

If so, what is the sensible size of a PR? Should I create a PR for every file, every 3-4 files in the documentation, or wait and submit a PR when I have read and made changes to most of the docs? Any preference?

jschendel · 2017-12-28T00:56:29Z

@tommyod : I don't think there's really a preference in terms of the size of a PR. Whatever works best for you should be fine. My advice is to lean towards submitting PR's more frequently as opposed to waiting to submit a huge number of changes at once. Waiting could lead to merge conflicts if other people are updating the same sections of the docs, which could lead to extra work resolving the conflicts. Thanks for improving the docs!

…8948)

DOC: greater consistency and spell-check for intro docs

4db4120

tommyod changed the title ~~DOC: greater consistency for intro docs~~ DOC: greater consistency and spell-check for intro docs Dec 26, 2017

jreback requested changes Dec 26, 2017

View reviewed changes

jreback added the Docs label Dec 26, 2017

jschendel reviewed Dec 26, 2017

View reviewed changes

Func references, link to python 3, spelling

e8cb0f3

jreback added this to the 0.23.0 milestone Dec 27, 2017

jreback approved these changes Dec 27, 2017

View reviewed changes

jreback merged commit 32aef5c into pandas-dev:master Dec 27, 2017

hexgnu pushed a commit to hexgnu/pandas that referenced this pull request Dec 28, 2017

DOC: greater consistency and spell-check for intro docs (pandas-dev#1…

96181d6

…8948)

This was referenced Dec 28, 2017

Spellcheck of docs, a few minor changes #18973

Merged

Spellcheck #19017

Merged

tommyod mentioned this pull request Jan 4, 2018

DOC: Spellcheck of merging.rst, reshaping.rst and timeseries.rst #19081

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC: greater consistency and spell-check for intro docs #18948

DOC: greater consistency and spell-check for intro docs #18948

tommyod commented Dec 26, 2017 •

edited

Loading

codecov bot commented Dec 26, 2017 •

edited

Loading

jreback left a comment

jreback Dec 26, 2017

jreback Dec 26, 2017

jreback Dec 26, 2017

jreback Dec 26, 2017

jreback Dec 26, 2017

jreback Dec 26, 2017

jreback Dec 26, 2017

jschendel Dec 26, 2017 •

edited

Loading

tommyod commented Dec 27, 2017

jreback commented Dec 27, 2017

tommyod commented Dec 27, 2017 •

edited

Loading

jschendel commented Dec 28, 2017

DOC: greater consistency and spell-check for intro docs #18948

DOC: greater consistency and spell-check for intro docs #18948

Conversation

tommyod commented Dec 26, 2017 • edited Loading

codecov bot commented Dec 26, 2017 • edited Loading

Codecov Report

jreback left a comment

Choose a reason for hiding this comment

jreback Dec 26, 2017

Choose a reason for hiding this comment

jreback Dec 26, 2017

Choose a reason for hiding this comment

jreback Dec 26, 2017

Choose a reason for hiding this comment

jreback Dec 26, 2017

Choose a reason for hiding this comment

jreback Dec 26, 2017

Choose a reason for hiding this comment

jreback Dec 26, 2017

Choose a reason for hiding this comment

jreback Dec 26, 2017

Choose a reason for hiding this comment

jschendel Dec 26, 2017 • edited Loading

Choose a reason for hiding this comment

tommyod commented Dec 27, 2017

jreback commented Dec 27, 2017

tommyod commented Dec 27, 2017 • edited Loading

jschendel commented Dec 28, 2017

tommyod commented Dec 26, 2017 •

edited

Loading

codecov bot commented Dec 26, 2017 •

edited

Loading

jschendel Dec 26, 2017 •

edited

Loading

tommyod commented Dec 27, 2017 •

edited

Loading