Add missing period to pandas.Series.interpolate docstring #22217

adamjstewart · 2018-08-06T16:01:14Z

Previously, the new in version message seemed like a run-on sentence:
https://pandas.pydata.org/pandas-docs/stable/generated/pandas.Series.interpolate.html

Also added code formatting for BPoly.from_derivatives reference.

Previously, the _new in version_ message seemed like a run-on sentence: https://pandas.pydata.org/pandas-docs/stable/generated/pandas.Series.interpolate.html Also added code formatting for BPoly.from_derivatives reference.

WillAyd · 2018-08-06T16:16:31Z

pandas/core/generic.py

@@ -6110,13 +6110,13 @@ def replace(self, to_replace=None, value=None, inplace=False, limit=None,
              <http://docs.scipy.org/doc/scipy/reference/interpolate.html#univariate-interpolation>`__
              and `tutorial documentation
              <http://docs.scipy.org/doc/scipy/reference/tutorial/interpolate.html>`__
-            * 'from_derivatives' refers to BPoly.from_derivatives which
+            * 'from_derivatives' refers to ``BPoly.from_derivatives`` which


I think we just use double backticks for literals so this is probably better served with just single back ticks. @datapythonista

A few lines above, I see scipy.interpolate.interp1d wrapped in double backticks. I figured we would want to do the same for scipy.interpolate.BPoly.from_derivatives. Do you want me to change scipy.interpolate.interp1d to single backticks?

P.S. Should these additionally be hyperlinks to the actual scipy docs? Or do the scipy docs reorganize enough that it wouldn't be stable?

Afaik double backticks are mainly used for code, as they are rendered in monospace. While single backticks don't have a specific meaning, as they can be customized. So, for my understanding, we should use single backticks in this case. But I think in many cases we're using double backticks for similar things.

About the links, they are built automatically for other parts of the documentation, by prefixing :class:, :meth:, :ref:... But I'm not sure if for external packages we've got it set up.

May be @TomAugspurger knows. Otherwise, I'll research and see what's the best we can do.

Links to scipy should work, since they're in our intersphinx mapping:

pandas/doc/source/conf.py

Lines 366 to 374 in 2156431

intersphinx_mapping = {

'statsmodels': ('http://www.statsmodels.org/devel/', None),

'matplotlib': ('http://matplotlib.org/', None),

'pandas-gbq': ('https://pandas-gbq.readthedocs.io/en/latest/', None),

'python': ('https://docs.python.org/3/', None),

'numpy': ('https://docs.scipy.org/doc/numpy/', None),

'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None),

'py': ('https://pylib.readthedocs.io/en/latest/', None)

}

so using :meth: is probably best.

codecov · 2018-08-06T16:57:24Z

Codecov Report

Merging #22217 into master will increase coverage by <.01%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master   #22217      +/-   ##
==========================================
+ Coverage   92.06%   92.06%   +<.01%     
==========================================
  Files         169      169              
  Lines       50694    50698       +4     
==========================================
+ Hits        46671    46676       +5     
+ Misses       4023     4022       -1

Flag	Coverage Δ
#multiple	`90.47% <ø> (ø)`	⬆️
#single	`42.32% <ø> (-0.01%)`	⬇️

Impacted Files	Coverage Δ
pandas/core/generic.py	`96.47% <ø> (ø)`	⬆️
pandas/core/internals/blocks.py	`94.45% <0%> (ø)`	⬆️
pandas/core/missing.py	`91.7% <0%> (+0.04%)`	⬆️
pandas/core/indexes/base.py	`96.43% <0%> (+0.05%)`	⬆️

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 2156431...2db1a0d. Read the comment docs.

adamjstewart · 2018-08-06T21:57:11Z

Alright, see if this is better. I added links to the actual scipy docs for those functions. I wasn't sure if you can do something like :py:func:``foo.bar`` to add backticks in addition to the link? rST linking has never been logical or clear to me...

datapythonista · 2018-08-07T12:15:06Z

Not sure about the :py:func: I think it should be just :func: if they are not methods. Did you try building the documentation, and see if it renders as expected? ./doc/make.py html should build it, and then you just need to find the interpolate method page in the build directory (doc/source/build/generated if I'm not wrong).

adamjstewart · 2018-08-07T18:45:02Z

@datapythonista I got the :py:func: syntax from http://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#role-py:func.

I tried building the docs but got the following error message:

$ ./make.py html
Running Sphinx v1.7.5

Configuration error:
There is a programable error in your configuration file:

Traceback (most recent call last):
  File "/Users/Adam/pandas/pandas/__init__.py", line 26, in <module>
    from pandas._libs import (hashtable as _hashtable,
  File "/Users/Adam/pandas/pandas/_libs/__init__.py", line 4, in <module>
    from .tslibs import (
  File "/Users/Adam/pandas/pandas/_libs/tslibs/__init__.py", line 4, in <module>
    from .conversion import normalize_date, localize_pydatetime, tz_convert_single
ModuleNotFoundError: No module named 'pandas._libs.tslibs.conversion'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/Users/Adam/anaconda3/lib/python3.6/site-packages/sphinx/config.py", line 161, in __init__
    execfile_(filename, config)
  File "/Users/Adam/anaconda3/lib/python3.6/site-packages/sphinx/util/pycompat.py", line 150, in execfile_
    exec_(code, _globals)
  File "conf.py", line 140, in <module>
    import pandas
  File "/Users/Adam/pandas/pandas/__init__.py", line 35, in <module>
    "the C extensions first.".format(module))
ImportError: C extension: No module named 'pandas._libs.tslibs.conversion' not built. If you want to import pandas from the source directory, you may need to run 'python setup.py build_ext --inplace --force' to build the C extensions first.

What am I missing here?

WillAyd · 2018-08-07T18:49:44Z

You need to build the C extensions:

python setup.py build_ext --inplace

adamjstewart · 2018-08-07T19:02:12Z

Thanks, but now I'm having troubles with cython:

$ python setup.py build_ext --inplace
running build_ext
pandas._libs.algos: -> [['pandas/_libs/algos.c']]
Traceback (most recent call last):
  File "setup.py", line 755, in <module>
    **setuptools_kwargs)
  File "/Users/Adam/anaconda3/lib/python3.6/site-packages/setuptools/__init__.py", line 129, in setup
    return distutils.core.setup(**attrs)
  File "/Users/Adam/anaconda3/lib/python3.6/distutils/core.py", line 148, in setup
    dist.run_commands()
  File "/Users/Adam/anaconda3/lib/python3.6/distutils/dist.py", line 955, in run_commands
    self.run_command(cmd)
  File "/Users/Adam/anaconda3/lib/python3.6/distutils/dist.py", line 974, in run_command
    cmd_obj.run()
  File "/Users/Adam/anaconda3/lib/python3.6/distutils/command/build_ext.py", line 339, in run
    self.build_extensions()
  File "setup.py", line 369, in build_extensions
    self.check_cython_extensions(self.extensions)
  File "setup.py", line 366, in check_cython_extensions
    """.format(src=src))
Exception: Cython-generated file 'pandas/_libs/algos.c' not found.
                Cython is required to compile pandas from a development branch.
                Please install Cython or download a release package of pandas.

I do have cython installed though...

$ pip install cython
Requirement already satisfied: cython in /Users/Adam/anaconda3/lib/python3.6/site-packages (0.27.3)
$ python
Python 3.6.5 |Anaconda custom (64-bit)| (default, Apr 26 2018, 08:42:37) 
[GCC 4.2.1 Compatible Clang 4.0.1 (tags/RELEASE_401/final)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import cython
>>> cython.__version__
'0.27.3'

WillAyd · 2018-08-07T19:05:44Z

Maybe try starting with a clean before building:

python setup.py clean --all

lmk

adamjstewart · 2018-08-07T19:49:36Z

Same error message. I also tried adding the --force flag suggested by the previous error message.

WillAyd · 2018-08-07T19:58:05Z

Are you running within an activated virtual environment? Set up looks OK but maybe something surprising going on with path resolution if not

adamjstewart · 2018-08-07T20:04:23Z

No virtual environment. I just updated Cython from 0.27.3 to 0.28.4 and it seems to be working now??

WillAyd · 2018-08-07T20:05:33Z

Makes sense. We just upped our min version dependency to 0.28.2

adamjstewart · 2018-08-07T20:19:29Z

Alright, I ran:

$ python make.py --num-jobs 4 --single Series.interpolate

and everything looks good:

However, the scipy function links aren't clickable. Is this just because it's a preview?

P.S. I also tried replacing :py:func: with :func: and it looks identical. If they both work, is :func: preferred?

TomAugspurger · 2018-08-07T20:38:48Z

Yes, just :func: If you're curious, the :py: is a domain http://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html We use the default Python domain.

…

On Tue, Aug 7, 2018 at 3:19 PM Adam J. Stewart ***@***.***> wrote: Alright, I ran: $ python make.py --num-jobs 4 --single Series.interpolate and everything looks good: [image: screen shot 2018-08-07 at 3 15 40 pm] <https://user-images.githubusercontent.com/12021217/43800038-d88217fa-9a54-11e8-98ec-49bc102dec6a.png> However, the scipy function links aren't clickable. Is this just because it's a preview? P.S. I also tried replacing :py:func: with :func: and it looks identical. If they both work, is :func: preferred? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#22217 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ABQHIpkR-xUU-YINtjPKSwfrJy4n30Q8ks5uOfZYgaJpZM4VwqGB> .

datapythonista · 2018-08-07T20:47:34Z

@adamjstewart I think sphinx does not create the links when we build with --single. Not sure why, but if you build the whole documentation, it'll take longer, but it should generate the links.

adamjstewart · 2018-08-07T21:12:50Z

@datapythonista I cleaned and rebuilt all of the docs this time but still no links. 🤷‍♂️

datapythonista · 2018-08-07T21:54:15Z

@adamjstewart did you check if the rest of the links (e.g. See Also sections) are working? For example, in Series.astype you've got links to other pandas methods and also to numpy. Not sure if the problem is in your environment, or in all links to scipy. Checking other links should help identify the problem.

adamjstewart · 2018-08-07T22:18:44Z

The "See Also" links are working. Links to numpy.where in pandas.DataFrame.where are working. Links to scipy.stats.gaussian_kde in pandas.DataFrame.plot.kde are working. But the links added in this PR are not.

datapythonista · 2018-08-07T22:26:50Z

pandas/core/generic.py

-              ``scipy.interpolate.interp1d``. Both 'polynomial' and 'spline'
-              require that you also specify an `order` (int),
-              e.g. df.interpolate(method='polynomial', order=4).
+              :func:`scipy.interpolate.interp1d`. Both 'polynomial' and


Seems like scipy.interpolate.interp1d is a class. May be that's the problem, as it requires :class: instead of :func:?

https://docs.scipy.org/doc/scipy/reference/generated/scipy.interpolate.interp1d.html

datapythonista · 2018-08-07T22:28:06Z

pandas/core/generic.py

@@ -6110,13 +6110,14 @@ def replace(self, to_replace=None, value=None, inplace=False, limit=None,
              <http://docs.scipy.org/doc/scipy/reference/interpolate.html#univariate-interpolation>`__
              and `tutorial documentation
              <http://docs.scipy.org/doc/scipy/reference/tutorial/interpolate.html>`__
-            * 'from_derivatives' refers to BPoly.from_derivatives which
+            * 'from_derivatives' refers to
+              :func:`scipy.interpolate.BPoly.from_derivatives` which


And this seems to be a method, so :meth: instead of :func:.

adamjstewart · 2018-08-07T22:35:59Z

@datapythonista That did the trick, thanks! For the record, Sphinx creates the links even with --single, so no need to build all the docs to test.

datapythonista

lgtm.

It's good to know that --single creates the links now, I think it didn't before (may be the problem was a different thing).

Thanks @adamjstewart for the contribution, this is a useful change.

jreback · 2018-08-08T10:39:52Z

thanks @adamjstewart

…#22217)

Add missing period to pandas.Series.interpolate docstring

74a2c65

Previously, the _new in version_ message seemed like a run-on sentence: https://pandas.pydata.org/pandas-docs/stable/generated/pandas.Series.interpolate.html Also added code formatting for BPoly.from_derivatives reference.

WillAyd reviewed Aug 6, 2018

View reviewed changes

Add links to external scipy docs

b53645e

datapythonista added the Docs label Aug 7, 2018

:py: is already the default domain, no need to specify

09b99d9

datapythonista reviewed Aug 7, 2018

View reviewed changes

Replace :func: with :class: and :meth:

2db1a0d

datapythonista approved these changes Aug 7, 2018

View reviewed changes

jreback added this to the 0.24.0 milestone Aug 8, 2018

jreback merged commit ac87c75 into pandas-dev:master Aug 8, 2018

adamjstewart deleted the docs/interpolate branch August 8, 2018 12:56

Sup3rGeo pushed a commit to Sup3rGeo/pandas that referenced this pull request Oct 1, 2018

Add missing period to pandas.Series.interpolate docstring (pandas-dev…

61105b9

…#22217)

	intersphinx_mapping = {
	'statsmodels': ('http://www.statsmodels.org/devel/', None),
	'matplotlib': ('http://matplotlib.org/', None),
	'pandas-gbq': ('https://pandas-gbq.readthedocs.io/en/latest/', None),
	'python': ('https://docs.python.org/3/', None),
	'numpy': ('https://docs.scipy.org/doc/numpy/', None),
	'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None),
	'py': ('https://pylib.readthedocs.io/en/latest/', None)
	}

Uh oh!

Add missing period to pandas.Series.interpolate docstring #22217

Add missing period to pandas.Series.interpolate docstring #22217

Uh oh!

Conversation

adamjstewart commented Aug 6, 2018

Uh oh!

WillAyd Aug 6, 2018

Choose a reason for hiding this comment

Uh oh!

adamjstewart Aug 6, 2018

Choose a reason for hiding this comment

Uh oh!

datapythonista Aug 6, 2018

Choose a reason for hiding this comment

Uh oh!

TomAugspurger Aug 6, 2018

Choose a reason for hiding this comment

Uh oh!

codecov bot commented Aug 6, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

adamjstewart commented Aug 6, 2018

Uh oh!

datapythonista commented Aug 7, 2018

Uh oh!

adamjstewart commented Aug 7, 2018

Uh oh!

WillAyd commented Aug 7, 2018

Uh oh!

adamjstewart commented Aug 7, 2018

Uh oh!

WillAyd commented Aug 7, 2018

Uh oh!

adamjstewart commented Aug 7, 2018

Uh oh!

WillAyd commented Aug 7, 2018

Uh oh!

adamjstewart commented Aug 7, 2018

Uh oh!

WillAyd commented Aug 7, 2018

Uh oh!

adamjstewart commented Aug 7, 2018

Uh oh!

TomAugspurger commented Aug 7, 2018 via email

Uh oh!

datapythonista commented Aug 7, 2018

Uh oh!

adamjstewart commented Aug 7, 2018

Uh oh!

datapythonista commented Aug 7, 2018

Uh oh!

adamjstewart commented Aug 7, 2018

Uh oh!

datapythonista Aug 7, 2018

Choose a reason for hiding this comment

Uh oh!

datapythonista Aug 7, 2018

Choose a reason for hiding this comment

Uh oh!

adamjstewart commented Aug 7, 2018

Uh oh!

datapythonista left a comment

Choose a reason for hiding this comment

Uh oh!

jreback commented Aug 8, 2018

Uh oh!

Uh oh!

codecov bot commented Aug 6, 2018 •

edited

Loading