DOC: Update Sphinx Deprecated Directive #16512

GuessWhoSamFoo · 2017-05-26T07:07:31Z

closes DOC: Update docs to use sphinx deprecated directive #16507
tests added / passed
passes git diff upstream/master --name-only -- '*.py' | flake8 --diff
whatsnew entry

XR #6581 for version numbers. Hopefully whitespace is okay.

codecov · 2017-05-26T07:40:30Z

Codecov Report

Merging #16512 into master will not change coverage.
The diff coverage is 100%.

@@           Coverage Diff           @@
##           master   #16512   +/-   ##
=======================================
  Coverage   90.43%   90.43%           
=======================================
  Files         161      161           
  Lines       51045    51045           
=======================================
  Hits        46161    46161           
  Misses       4884     4884

Flag	Coverage Δ
#multiple	`88.27% <100%> (ø)`	⬆️
#single	`40.16% <100%> (ø)`	⬆️

Impacted Files	Coverage Δ
pandas/core/generic.py	`92.16% <ø> (ø)`	⬆️
pandas/core/series.py	`94.71% <ø> (ø)`	⬆️
pandas/io/parsers.py	`95.33% <ø> (ø)`	⬆️
pandas/io/excel.py	`62.31% <ø> (ø)`	⬆️
pandas/core/indexes/datetimes.py	`95.33% <ø> (ø)`	⬆️
pandas/core/panelnd.py	`98.21% <ø> (ø)`	⬆️
pandas/core/window.py	`96.48% <ø> (ø)`	⬆️
pandas/core/sparse/array.py	`91.46% <ø> (ø)`	⬆️
pandas/core/common.py	`91.39% <ø> (ø)`	⬆️
pandas/core/indexes/base.py	`95.74% <ø> (ø)`	⬆️
... and 7 more

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 e81f3cc...400bb40. Read the comment docs.

codecov · 2017-05-26T07:40:30Z

Codecov Report

Merging #16512 into master will not change coverage.
The diff coverage is 100%.

@@           Coverage Diff           @@
##           master   #16512   +/-   ##
=======================================
  Coverage   90.43%   90.43%           
=======================================
  Files         161      161           
  Lines       51045    51045           
=======================================
  Hits        46161    46161           
  Misses       4884     4884

Flag	Coverage Δ
#multiple	`88.27% <100%> (ø)`	⬆️
#single	`40.16% <100%> (ø)`	⬆️

Impacted Files	Coverage Δ
pandas/core/generic.py	`92.16% <ø> (ø)`	⬆️
pandas/core/strings.py	`98.48% <ø> (ø)`	⬆️
pandas/core/sparse/array.py	`91.46% <ø> (ø)`	⬆️
pandas/core/panelnd.py	`98.21% <ø> (ø)`	⬆️
pandas/core/indexes/period.py	`92.74% <ø> (ø)`	⬆️
pandas/core/categorical.py	`95.91% <ø> (ø)`	⬆️
pandas/core/window.py	`96.48% <ø> (ø)`	⬆️
pandas/io/sql.py	`94.79% <ø> (ø)`	⬆️
pandas/core/indexes/datetimes.py	`95.33% <ø> (ø)`	⬆️
pandas/core/series.py	`94.71% <ø> (ø)`	⬆️
... and 7 more

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 e81f3cc...400bb40. Read the comment docs.

codecov · 2017-05-26T07:40:44Z

Codecov Report

Merging #16512 into master will not change coverage.
The diff coverage is 100%.

@@           Coverage Diff           @@
##           master   #16512   +/-   ##
=======================================
  Coverage   90.93%   90.93%           
=======================================
  Files         161      161           
  Lines       49280    49280           
=======================================
  Hits        44814    44814           
  Misses       4466     4466

Flag	Coverage Δ
#multiple	`88.7% <100%> (ø)`	⬆️
#single	`40.17% <100%> (ø)`	⬆️

Impacted Files	Coverage Δ
pandas/io/parsers.py	`95.43% <ø> (ø)`	⬆️
pandas/core/window.py	`96.49% <ø> (ø)`	⬆️
pandas/io/sql.py	`94.79% <ø> (ø)`	⬆️
pandas/core/panelnd.py	`98.21% <ø> (ø)`	⬆️
pandas/core/strings.py	`98.48% <ø> (ø)`	⬆️
pandas/core/indexes/datetimes.py	`95.33% <ø> (ø)`	⬆️
pandas/core/series.py	`94.9% <ø> (ø)`	⬆️
pandas/core/sparse/array.py	`91.46% <ø> (ø)`	⬆️
pandas/core/panel4d.py	`100% <ø> (ø)`	⬆️
pandas/core/common.py	`91.44% <ø> (ø)`	⬆️
... and 4 more

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 1265c27...8f31b83. Read the comment docs.

jreback · 2017-05-26T12:01:38Z

doc/source/io.rst

-  DEPRECATED: this argument will be removed in a future version. Please call
-  ``pd.read_csv(...).to_records()`` instead.
+  .. deprecated:: 0.18.2
+     This argument will be removed in a future version. Please call


I would eliminate things like: This argument will be removed in a future version. (look for occurences in the changes you made)

as the deprecated tag already has this (I think)

jreback · 2017-05-26T12:01:54Z

doc/source/io.rst

 skip_footer : int, default ``0``
-  DEPRECATED: use the ``skipfooter`` parameter instead, as they are identical
+  .. deprecated:: 0.19.0
+     Use the ``skipfooter`` parameter instead, as they are identical


e.g. this like this

jorisvandenbossche

Added some comments.

Can you show how it looks like when rendered in html with sphinx? (eg screenshot)

Main comment is that I am not sure it is a good idea to do this conversion when the 'DEPRECATED' is the first sentence of a docstring (but to be sure, we should actually test what the api summary tables would look like when using it)

jorisvandenbossche · 2017-05-31T22:26:12Z

doc/sphinxext/numpydoc/README.rst

  each entry to have a separate page.

- numpydoc_edit_link: bool  (DEPRECATED -- edit your HTML template instead)
+- numpydoc_edit_link: bool


please leave this one as is (numpydoc's source is just included in pandas, we should adapt it only minimally)

jorisvandenbossche · 2017-05-31T22:26:38Z

doc/source/io.rst

 as_recarray : boolean, default ``False``
-  DEPRECATED: this argument will be removed in a future version. Please call
-  ``pd.read_csv(...).to_records()`` instead.
+  .. deprecated:: 0.18.2


When using the deprecated directive, you will need to add blank lines around it

jorisvandenbossche · 2017-05-31T22:28:09Z

pandas/_libs/tslib.pyx

        """
-        DEPRECATED: use :meth:`to_pydatetime` instead.
+        .. deprecated:: 0.19.0
+           Use :meth:`to_pydatetime` instead.


Can you leave this one as is? The thing is that the first sentence of the docstring gets added to the API overview. So the actual "DEPRECATED .. " is then more useful as the directive code (although I am actually not sure what sphinx would put in the api summary table)

It seems sphinx only parses the first line to the summary table as expected. The changes have been reverted to avoid losing information in the API summary table.

jorisvandenbossche · 2017-05-31T22:28:46Z

pandas/core/frame.py

        """
-        DEPRECATED: use :meth:`DataFrame.sort_index`
+        .. deprecated:: 0.20.0
+           Use :meth:`DataFrame.sort_index`


Same comment as above for this one, and some others below as well

jreback · 2017-06-10T19:09:09Z

can you rebase and update?

GuessWhoSamFoo · 2017-06-15T15:47:08Z

My apologies for the late update - been traveling with limited wifi access. Updated per comments to avoid losing information in the API summary table when using sphinx directives.

jorisvandenbossche

Thanks for the updates!

jorisvandenbossche · 2017-06-15T19:29:47Z

pandas/core/generic.py

    def convert_objects(self, convert_dates=True, convert_numeric=False,
                        convert_timedeltas=True, copy=True):
        """
-        Deprecated.


This one should not be removed I think

jorisvandenbossche · 2017-06-15T20:22:45Z

pandas/core/strings.py

    na : default NaN, fill value for missing values.
-    as_indexer : DEPRECATED
+    as_indexer : False, by default, gives deprecated behavior better
+        achieved using str_extract. True return boolean indexer.


This is not fully correct. It is just ignored, so the explanation for True or False doesn't matter.

jorisvandenbossche · 2017-06-15T20:24:30Z

pandas/io/sql.py

-        DEPRECATED: this parameter will be removed in a future version
+        .. deprecated:: 0.19.0
+           'sqlite' is the only supported option if SQLAlchemy is not
+           installed.


'installed' is not fully correct, as you can use the sqlite backend also when sqlalchemy is installed. So I would make 'used' of it.

(the same for all the other occurrences of this one both in this file as in generic.py)

jorisvandenbossche · 2017-06-15T20:25:54Z

doc/source/style.ipynb

@@ -1,1185 +0,0 @@
-{


It seems you deleted this file by accident?

jorisvandenbossche · 2017-06-15T20:28:09Z

pandas/core/generic.py

        """
-        DEPRECATED: consolidate will be an internal implementation only.
+        .. deprecated:: 0.20.0
+           Consolidate will be an internal implementation only.


Same comment here as previous. By putting this deprecated directive on the first line, it gets less informative in a api summary table

jorisvandenbossche · 2017-06-15T20:28:52Z

pandas/core/series.py

    def sortlevel(self, level=0, ascending=True, sort_remaining=True):
        """
-        DEPRECATED: use :meth:`Series.sort_index`
+        .. deprecated:: 0.20.0


This one I would leave as well

…nto sphinx_deprecate

jorisvandenbossche · 2017-06-27T07:23:49Z

@GuessWhoSamFoo Thanks!

GuessWhoSamFoo added 2 commits May 25, 2017 23:53

DOC: Added sphinx deprecated directive XR#6581

4c73c42

Fixed whitespace

400bb40

GuessWhoSamFoo changed the title ~~DOC: Update Sphinx Deprecaded Directive~~ DOC: Update Sphinx Deprecated Directive May 26, 2017

jreback added the Docs label May 26, 2017

jreback reviewed May 26, 2017

View reviewed changes

Removed references to future versions

135f8d0

jorisvandenbossche reviewed May 31, 2017

View reviewed changes

GuessWhoSamFoo added 3 commits June 15, 2017 11:14

Updated per comments

7fccb78

Rendered HTML using sphinx to check output

9f945c2

Resolve merge conflicts

5d8db3f

jorisvandenbossche reviewed Jun 15, 2017

View reviewed changes

GuessWhoSamFoo added 3 commits June 25, 2017 14:26

Merge branch 'master' into sphinx_deprecate

c281c04

Restored deleted file; updated per comments

4dcab50

Merge branch 'sphinx_deprecate' of github.com:GuessWhoSamFoo/pandas i…

8f31b83

…nto sphinx_deprecate

jorisvandenbossche merged commit f6f5ce5 into pandas-dev:master Jun 27, 2017

jorisvandenbossche added this to the 0.21.0 milestone Jun 27, 2017

GuessWhoSamFoo deleted the sphinx_deprecate branch September 7, 2017 20:49

Uh oh!

DOC: Update Sphinx Deprecated Directive #16512

DOC: Update Sphinx Deprecated Directive #16512

Uh oh!

Conversation

GuessWhoSamFoo commented May 26, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented May 26, 2017

Codecov Report

Uh oh!

codecov bot commented May 26, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

codecov bot commented May 26, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jorisvandenbossche left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jreback commented Jun 10, 2017

Uh oh!

GuessWhoSamFoo commented Jun 15, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jorisvandenbossche left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jorisvandenbossche commented Jun 27, 2017

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

GuessWhoSamFoo commented May 26, 2017 •

edited

Loading

codecov bot commented May 26, 2017 •

edited

Loading

codecov bot commented May 26, 2017 •

edited

Loading

GuessWhoSamFoo commented Jun 15, 2017 •

edited

Loading