New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 2 commits into from Dec 27, 2017

Conversation

Projects
None yet
3 participants
@tommyod
Contributor

tommyod commented Dec 26, 2017

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

This comment has been minimized.

codecov bot commented Dec 26, 2017

Codecov Report

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

Impacted file tree graph

@@            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.

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

@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.

@@ -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``.

This comment has been minimized.

@jreback

jreback Dec 26, 2017

Contributor

can you make this a func reference

@@ -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.

This comment has been minimized.

@jreback

jreback Dec 26, 2017

Contributor

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

This comment has been minimized.

@jreback

jreback Dec 26, 2017

Contributor

like on line 866

@@ -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.

This comment has been minimized.

@jreback

jreback Dec 26, 2017

Contributor

can you add the refernce here

@@ -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.

This comment has been minimized.

@jreback

jreback Dec 26, 2017

Contributor

a comma before for instance

@@ -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``.

This comment has been minimized.

@jreback

jreback Dec 26, 2017

Contributor

can you add the reference

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

This comment has been minimized.

@jreback

jreback Dec 26, 2017

Contributor

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

@jreback jreback added the Docs label Dec 26, 2017

@@ -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

This comment has been minimized.

@jschendel

jschendel Dec 26, 2017

Member

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

@tommyod

This comment has been minimized.

Contributor

tommyod commented Dec 27, 2017

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

@jreback jreback added this to the 0.23.0 milestone Dec 27, 2017

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

3 checks passed

ci/circleci Your tests passed on CircleCI!
Details
continuous-integration/appveyor/pr AppVeyor build succeeded
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details
@jreback

This comment has been minimized.

Contributor

jreback commented Dec 27, 2017

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

This comment has been minimized.

Contributor

tommyod commented Dec 27, 2017

@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

This comment has been minimized.

Member

jschendel commented Dec 28, 2017

@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!

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

This was referenced Dec 28, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment