From f17747fb9c5fc7d274daa28c0736aa27679f9ebc Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Thu, 1 Mar 2018 14:12:16 +0100 Subject: [PATCH 01/20] let doctest fail travis if they fail --- ci/build_docs.sh | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/ci/build_docs.sh b/ci/build_docs.sh index a038304fe0f7a..7aefac7b3e133 100755 --- a/ci/build_docs.sh +++ b/ci/build_docs.sh @@ -16,6 +16,7 @@ if [ "$?" != "0" ]; then exit 0 fi +RET=0 if [ "$DOC" ]; then @@ -68,6 +69,8 @@ if [ "$DOC" ]; then pandas/core/reshape/reshape.py \ pandas/core/reshape/tile.py + RET="$?" + fi -exit 0 +exit "$RET" From d24bbd24282517cf404a7e8e1378550ef261fc14 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Thu, 1 Mar 2018 14:13:54 +0100 Subject: [PATCH 02/20] remove check for building docs, we also want to test if docstrings changed --- ci/build_docs.sh | 8 -------- 1 file changed, 8 deletions(-) diff --git a/ci/build_docs.sh b/ci/build_docs.sh index 7aefac7b3e133..6a597992b57a8 100755 --- a/ci/build_docs.sh +++ b/ci/build_docs.sh @@ -8,14 +8,6 @@ fi cd "$TRAVIS_BUILD_DIR" echo "inside $0" -git show --pretty="format:" --name-only HEAD~5.. --first-parent | grep -P "rst|txt|doc" - -if [ "$?" != "0" ]; then - echo "Skipping doc build, none were modified" - # nope, skip docs build - exit 0 -fi - RET=0 if [ "$DOC" ]; then From 47f703425bb1d003374164b85a58d3709f7ab3fd Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Thu, 1 Mar 2018 14:42:03 +0100 Subject: [PATCH 03/20] Add Series and DataFrame doctests --- ci/build_docs.sh | 18 +++++++++++++++++- setup.cfg | 1 + 2 files changed, 18 insertions(+), 1 deletion(-) diff --git a/ci/build_docs.sh b/ci/build_docs.sh index 6a597992b57a8..b46511621b570 100755 --- a/ci/build_docs.sh +++ b/ci/build_docs.sh @@ -61,8 +61,24 @@ if [ "$DOC" ]; then pandas/core/reshape/reshape.py \ pandas/core/reshape/tile.py - RET="$?" + if [ $? -ne "0" ]; then + RET=1 + fi + # DataFrame docstrings + pytest --doctest-modules pandas/core/series.py -k"-agg -apply -applymap -assign -eval -isin -itertuples -join -merge -nlargest -nsmallest -nunique -pivot -pivot_table -quantile -query -reindex -reindex_axis -replace -round -select_dtypes -set_index -stack -to_dict -to_excel -to_stata" + + if [ $? -ne "0" ]; then + RET=1 + fi + + # Series docstrings + pytest --doctest-modules pandas/core/series.py -k"-agg -apply -map -nlargest -nonzero -nsmallest -reindex -replace -searchsorted -sort_values -to_dict -to_excel" + + if [ $? -ne "0" ]; then + RET=1 + fi + fi exit "$RET" diff --git a/setup.cfg b/setup.cfg index 942b2b0a1a0bf..ca62574b0300f 100644 --- a/setup.cfg +++ b/setup.cfg @@ -32,3 +32,4 @@ markers = slow: mark a test as slow network: mark a test as network high_memory: mark a test as a high-memory only +doctest_optionflags = NORMALIZE_WHITESPACE IGNORE_EXCEPTION_DETAIL From 67f4ae81883f13bc701652dedcabca42412d9c08 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Thu, 1 Mar 2018 21:26:07 +0100 Subject: [PATCH 04/20] try propagating exit value --- ci/run_build_docs.sh | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/ci/run_build_docs.sh b/ci/run_build_docs.sh index 2909b9619552e..8d29672d3d1ee 100755 --- a/ci/run_build_docs.sh +++ b/ci/run_build_docs.sh @@ -7,4 +7,6 @@ echo "inside $0" # wait until subprocesses finish (build_docs.sh) wait -exit 0 +RET="$?" + +exit "$RET" From 5caf04b12ee0ff166b1b4d7b69e774b3d773015b Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Mon, 9 Apr 2018 15:45:38 +0200 Subject: [PATCH 05/20] move to separate file --- .travis.yml | 1 + ci/build_docs.sh | 31 +------------------------------ ci/doctests.sh | 43 +++++++++++++++++++++++++++++++++++++++++++ ci/run_build_docs.sh | 4 +--- 4 files changed, 46 insertions(+), 33 deletions(-) create mode 100755 ci/doctests.sh diff --git a/.travis.yml b/.travis.yml index 22ef6c819c6d4..1bc2c41db1d6a 100644 --- a/.travis.yml +++ b/.travis.yml @@ -115,6 +115,7 @@ script: - ci/script_single.sh - ci/script_multi.sh - ci/lint.sh + - ci/doctests.sh - echo "checking imports" - source activate pandas && python ci/check_imports.py - echo "script done" diff --git a/ci/build_docs.sh b/ci/build_docs.sh index b46511621b570..d87f1b6e1dd62 100755 --- a/ci/build_docs.sh +++ b/ci/build_docs.sh @@ -8,8 +8,6 @@ fi cd "$TRAVIS_BUILD_DIR" echo "inside $0" -RET=0 - if [ "$DOC" ]; then echo "Will build docs" @@ -52,33 +50,6 @@ if [ "$DOC" ]; then git remote -v git push origin gh-pages -f - - echo "Running doctests" - cd "$TRAVIS_BUILD_DIR" - pytest --doctest-modules \ - pandas/core/reshape/concat.py \ - pandas/core/reshape/pivot.py \ - pandas/core/reshape/reshape.py \ - pandas/core/reshape/tile.py - - if [ $? -ne "0" ]; then - RET=1 - fi - - # DataFrame docstrings - pytest --doctest-modules pandas/core/series.py -k"-agg -apply -applymap -assign -eval -isin -itertuples -join -merge -nlargest -nsmallest -nunique -pivot -pivot_table -quantile -query -reindex -reindex_axis -replace -round -select_dtypes -set_index -stack -to_dict -to_excel -to_stata" - - if [ $? -ne "0" ]; then - RET=1 - fi - - # Series docstrings - pytest --doctest-modules pandas/core/series.py -k"-agg -apply -map -nlargest -nonzero -nsmallest -reindex -replace -searchsorted -sort_values -to_dict -to_excel" - - if [ $? -ne "0" ]; then - RET=1 - fi - fi -exit "$RET" +exit 0 diff --git a/ci/doctests.sh b/ci/doctests.sh new file mode 100755 index 0000000000000..d8f38aba3053e --- /dev/null +++ b/ci/doctests.sh @@ -0,0 +1,43 @@ +#!/bin/bash + +echo "inside $0" + + +source activate pandas +cd "$TRAVIS_BUILD_DIR" + +RET=0 + +if [ "$LINT" ]; then + + echo "Running doctests" + + pytest --doctest-modules \ + pandas/core/reshape/concat.py \ + pandas/core/reshape/pivot.py \ + pandas/core/reshape/reshape.py \ + pandas/core/reshape/tile.py -v + + if [ $? -ne "0" ]; then + RET=1 + fi + + # DataFrame docstrings + pytest --doctest-modules pandas/core/frame.py -k"-agg -apply -applymap -assign -eval -isin -itertuples -join -merge -nlargest -nsmallest -nunique -pivot -pivot_table -quantile -query -reindex -reindex_axis -replace -round -select_dtypes -set_index -stack -to_dict -to_excel -to_stata" -v + + if [ $? -ne "0" ]; then + RET=1 + fi + + # Series docstrings + pytest --doctest-modules pandas/core/series.py -k"-agg -apply -map -nlargest -nonzero -nsmallest -reindex -replace -searchsorted -sort_values -to_dict -to_excel" -v + + if [ $? -ne "0" ]; then + RET=1 + fi + +else + echo "NOT running doctests" +fi + +exit $RET diff --git a/ci/run_build_docs.sh b/ci/run_build_docs.sh index 8d29672d3d1ee..2909b9619552e 100755 --- a/ci/run_build_docs.sh +++ b/ci/run_build_docs.sh @@ -7,6 +7,4 @@ echo "inside $0" # wait until subprocesses finish (build_docs.sh) wait -RET="$?" - -exit "$RET" +exit 0 From 10cf824d2136e834de5152c6f669582fd1ad8afc Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Mon, 9 Apr 2018 15:59:20 +0200 Subject: [PATCH 06/20] add read functions --- ci/doctests.sh | 24 +++++++++++++++++------- 1 file changed, 17 insertions(+), 7 deletions(-) diff --git a/ci/doctests.sh b/ci/doctests.sh index d8f38aba3053e..98ed8422ea7a2 100755 --- a/ci/doctests.sh +++ b/ci/doctests.sh @@ -12,25 +12,35 @@ if [ "$LINT" ]; then echo "Running doctests" - pytest --doctest-modules \ - pandas/core/reshape/concat.py \ - pandas/core/reshape/pivot.py \ - pandas/core/reshape/reshape.py \ - pandas/core/reshape/tile.py -v + # top-level reshaping functions + pytest --doctest-modules -v \ + pandas/core/reshape/concat.py \ + pandas/core/reshape/pivot.py \ + pandas/core/reshape/reshape.py \ + pandas/core/reshape/tile.py + + if [ $? -ne "0" ]; then + RET=1 + fi + + # top-level io functionality + pytest --doctest-modules -v pandas/io/* -k "read_" if [ $? -ne "0" ]; then RET=1 fi # DataFrame docstrings - pytest --doctest-modules pandas/core/frame.py -k"-agg -apply -applymap -assign -eval -isin -itertuples -join -merge -nlargest -nsmallest -nunique -pivot -pivot_table -quantile -query -reindex -reindex_axis -replace -round -select_dtypes -set_index -stack -to_dict -to_excel -to_stata" -v + pytest --doctest-modules -v \ + pandas/core/frame.py -k"-agg -apply -applymap -assign -eval -isin -itertuples -join -merge -nlargest -nsmallest -nunique -pivot -pivot_table -quantile -query -reindex -reindex_axis -replace -round -select_dtypes -set_index -stack -to_dict -to_excel -to_stata" if [ $? -ne "0" ]; then RET=1 fi # Series docstrings - pytest --doctest-modules pandas/core/series.py -k"-agg -apply -map -nlargest -nonzero -nsmallest -reindex -replace -searchsorted -sort_values -to_dict -to_excel" -v + pytest --doctest-modules -v \ + pandas/core/series.py -k"-agg -apply -map -nlargest -nonzero -nsmallest -reindex -replace -searchsorted -to_dict -to_excel" if [ $? -ne "0" ]; then RET=1 From 32f6d1c88779c2b8d3c642cdcd0d82c1441c9ea3 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Mon, 9 Apr 2018 17:27:12 +0200 Subject: [PATCH 07/20] run doctests on python 3.6 build --- .travis.yml | 3 +-- ci/doctests.sh | 2 +- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/.travis.yml b/.travis.yml index 586dd5a507f7e..ab2b76352d6d5 100644 --- a/.travis.yml +++ b/.travis.yml @@ -49,10 +49,9 @@ matrix: apt: packages: - python-gtk2 - # In allow_failures - dist: trusty env: - - JOB="3.6" TEST_ARGS="--skip-slow --skip-network" PANDAS_TESTING_MODE="deprecate" CONDA_FORGE=true COVERAGE=true + - JOB="3.6" TEST_ARGS="--skip-slow --skip-network" PANDAS_TESTING_MODE="deprecate" CONDA_FORGE=true COVERAGE=true DOCTEST=true # In allow_failures - dist: trusty env: diff --git a/ci/doctests.sh b/ci/doctests.sh index 98ed8422ea7a2..a33923aa0a1c8 100755 --- a/ci/doctests.sh +++ b/ci/doctests.sh @@ -8,7 +8,7 @@ cd "$TRAVIS_BUILD_DIR" RET=0 -if [ "$LINT" ]; then +if [ "$DOCTEST" ]; then echo "Running doctests" From 5833f86aa878d645241689a53cd70496b88f11d1 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Tue, 10 Apr 2018 13:20:53 +0200 Subject: [PATCH 08/20] ensure doctest collection does not fail --- pandas/core/config.py | 2 +- pandas/util/testing.py | 9 ++++----- 2 files changed, 5 insertions(+), 6 deletions(-) diff --git a/pandas/core/config.py b/pandas/core/config.py index 369e0568346ef..cc8ba051626d0 100644 --- a/pandas/core/config.py +++ b/pandas/core/config.py @@ -384,7 +384,7 @@ class option_context(object): -------- >>> with option_context('display.max_rows', 10, 'display.max_columns', 5): - ... + ... ... """ diff --git a/pandas/util/testing.py b/pandas/util/testing.py index 6e13a17eba68c..fde878996c931 100644 --- a/pandas/util/testing.py +++ b/pandas/util/testing.py @@ -554,7 +554,7 @@ def _valid_locales(locales, normalize): def capture_stdout(f): - """ + r""" Decorator to capture stdout in a buffer so that it can be checked (or suppressed) during testing. @@ -572,7 +572,6 @@ def capture_stdout(f): -------- >>> from pandas.util.testing import capture_stdout - >>> >>> import sys >>> >>> @capture_stdout @@ -602,7 +601,7 @@ def wrapper(*args, **kwargs): def capture_stderr(f): - """ + r""" Decorator to capture stderr in a buffer so that it can be checked (or suppressed) during testing. @@ -620,7 +619,6 @@ def capture_stderr(f): -------- >>> from pandas.util.testing import capture_stderr - >>> >>> import sys >>> >>> @capture_stderr @@ -2304,7 +2302,7 @@ def stdin_encoding(encoding=None): def assert_raises_regex(_exception, _regexp, _callable=None, *args, **kwargs): - r""" + """ Check that the specified Exception is raised and that the error message matches a given regular expression pattern. This may be a regular expression object or a string containing a regular expression suitable @@ -2330,6 +2328,7 @@ def assert_raises_regex(_exception, _regexp, _callable=None, AssertionError: "pear" does not match "'apple'" You can also use this in a with statement. + >>> with assert_raises_regex(TypeError, 'unsupported operand type\(s\)'): ... 1 + {} >>> with assert_raises_regex(TypeError, 'banana'): From 1d8e592208f923272c86de6ee71123ce84478a0c Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Tue, 10 Apr 2018 13:21:18 +0200 Subject: [PATCH 09/20] temp: check running all doctests on travis --- ci/doctests.sh | 54 ++++++++++++++++++++++++++++---------------------- 1 file changed, 30 insertions(+), 24 deletions(-) diff --git a/ci/doctests.sh b/ci/doctests.sh index a33923aa0a1c8..e37ccb47591a8 100755 --- a/ci/doctests.sh +++ b/ci/doctests.sh @@ -12,39 +12,45 @@ if [ "$DOCTEST" ]; then echo "Running doctests" - # top-level reshaping functions - pytest --doctest-modules -v \ - pandas/core/reshape/concat.py \ - pandas/core/reshape/pivot.py \ - pandas/core/reshape/reshape.py \ - pandas/core/reshape/tile.py - + pytest --doctest-modules --ignore=pandas/tests -v pandas if [ $? -ne "0" ]; then RET=1 fi - # top-level io functionality - pytest --doctest-modules -v pandas/io/* -k "read_" - if [ $? -ne "0" ]; then - RET=1 - fi + # # top-level reshaping functions + # pytest --doctest-modules -v \ + # pandas/core/reshape/concat.py \ + # pandas/core/reshape/pivot.py \ + # pandas/core/reshape/reshape.py \ + # pandas/core/reshape/tile.py - # DataFrame docstrings - pytest --doctest-modules -v \ - pandas/core/frame.py -k"-agg -apply -applymap -assign -eval -isin -itertuples -join -merge -nlargest -nsmallest -nunique -pivot -pivot_table -quantile -query -reindex -reindex_axis -replace -round -select_dtypes -set_index -stack -to_dict -to_excel -to_stata" + # if [ $? -ne "0" ]; then + # RET=1 + # fi - if [ $? -ne "0" ]; then - RET=1 - fi + # # top-level io functionality + # pytest --doctest-modules -v pandas/io/* -k "read_" - # Series docstrings - pytest --doctest-modules -v \ - pandas/core/series.py -k"-agg -apply -map -nlargest -nonzero -nsmallest -reindex -replace -searchsorted -to_dict -to_excel" + # if [ $? -ne "0" ]; then + # RET=1 + # fi - if [ $? -ne "0" ]; then - RET=1 - fi + # # DataFrame docstrings + # pytest --doctest-modules -v \ + # pandas/core/frame.py -k"-agg -apply -applymap -assign -eval -isin -itertuples -join -merge -nlargest -nsmallest -nunique -pivot -pivot_table -quantile -query -reindex -reindex_axis -replace -round -select_dtypes -set_index -stack -to_dict -to_excel -to_stata" + + # if [ $? -ne "0" ]; then + # RET=1 + # fi + + # # Series docstrings + # pytest --doctest-modules -v \ + # pandas/core/series.py -k"-agg -apply -map -nlargest -nonzero -nsmallest -reindex -replace -searchsorted -to_dict -to_excel" + + # if [ $? -ne "0" ]; then + # RET=1 + # fi else echo "NOT running doctests" From 3add36c86316816adc5638eab5b2ae9969581cb2 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Tue, 10 Apr 2018 17:04:08 +0200 Subject: [PATCH 10/20] cummax giving core dump --- ci/doctests.sh | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/ci/doctests.sh b/ci/doctests.sh index e37ccb47591a8..eec9f3271e8a6 100755 --- a/ci/doctests.sh +++ b/ci/doctests.sh @@ -12,7 +12,9 @@ if [ "$DOCTEST" ]; then echo "Running doctests" - pytest --doctest-modules --ignore=pandas/tests -v pandas + pytest --doctest-modules --ignore=pandas/tests -v pandas \ + -k"-pandas.core.frame.DataFrame.cum" + if [ $? -ne "0" ]; then RET=1 fi From 9317d3178c12c2142d0c619d39af7062669afcf6 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Sun, 8 Jul 2018 11:07:13 -0500 Subject: [PATCH 11/20] try --- ci/doctests.sh | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/ci/doctests.sh b/ci/doctests.sh index eec9f3271e8a6..652a6f11f01d4 100755 --- a/ci/doctests.sh +++ b/ci/doctests.sh @@ -12,8 +12,7 @@ if [ "$DOCTEST" ]; then echo "Running doctests" - pytest --doctest-modules --ignore=pandas/tests -v pandas \ - -k"-pandas.core.frame.DataFrame.cum" + pytest --doctest-modules --ignore=pandas/tests -v pandas/core/frame.py if [ $? -ne "0" ]; then RET=1 From 7845ea3c5bb7b79b9df64583d6867963f75ef31a Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Sun, 8 Jul 2018 22:24:56 -0500 Subject: [PATCH 12/20] remove snippet that causes segfault --- pandas/core/frame.py | 8 -------- 1 file changed, 8 deletions(-) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index 7e8fef9644d8c..6e7c06799d9ea 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -6939,14 +6939,6 @@ def count(self, axis=0, level=None, numeric_only=False): 3 3 4 3 dtype: int64 - - Counts for one level of a `MultiIndex`: - - >>> df.set_index(["Person", "Single"]).count(level="Person") - Age - Person - John 2 - Myla 1 """ axis = self._get_axis_number(axis) if level is not None: From 9837682de2867feb3ba3b71f64c1cd72b8d12a7c Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Thu, 16 Aug 2018 11:18:08 +0200 Subject: [PATCH 13/20] fix DataFrame docstring --- pandas/core/frame.py | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index 78ad9728800d6..411e3d970ebf5 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -314,15 +314,13 @@ class DataFrame(NDFrame): Constructing DataFrame from numpy ndarray: - >>> df2 = pd.DataFrame(np.random.randint(low=0, high=10, size=(5, 5)), - ... columns=['a', 'b', 'c', 'd', 'e']) + >>> df2 = pd.DataFrame(np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]]), + ... columns=['a', 'b', 'c']) >>> df2 - a b c d e - 0 2 8 8 3 4 - 1 4 2 9 0 9 - 2 1 0 7 8 0 - 3 5 1 7 1 3 - 4 6 0 2 4 2 + a b c + 0 1 2 3 + 1 4 5 6 + 2 7 8 9 See also -------- From 5d468d2bd6375792a6d4903cc34e4f9f9d57174c Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Thu, 16 Aug 2018 11:18:28 +0200 Subject: [PATCH 14/20] test checking all frame docstrings with skipped ones --- ci/doctests.sh | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/ci/doctests.sh b/ci/doctests.sh index 652a6f11f01d4..a337210837692 100755 --- a/ci/doctests.sh +++ b/ci/doctests.sh @@ -12,11 +12,11 @@ if [ "$DOCTEST" ]; then echo "Running doctests" - pytest --doctest-modules --ignore=pandas/tests -v pandas/core/frame.py + # pytest --doctest-modules --ignore=pandas/tests -v pandas/core/frame.py - if [ $? -ne "0" ]; then - RET=1 - fi + # if [ $? -ne "0" ]; then + # RET=1 + # fi # # top-level reshaping functions @@ -37,13 +37,13 @@ if [ "$DOCTEST" ]; then # RET=1 # fi - # # DataFrame docstrings - # pytest --doctest-modules -v \ - # pandas/core/frame.py -k"-agg -apply -applymap -assign -eval -isin -itertuples -join -merge -nlargest -nsmallest -nunique -pivot -pivot_table -quantile -query -reindex -reindex_axis -replace -round -select_dtypes -set_index -stack -to_dict -to_excel -to_stata" + # DataFrame docstrings + pytest --doctest-modules -v pandas/core/frame.py \ + -k"-assign -axes -combine -isin -itertuples -join -nlargest -nsmallest -nunique -pivot_table -quantile -query -reindex -reindex_axis -replace -round -set_index -stack -to_dict -to_records -to_stata -transform" - # if [ $? -ne "0" ]; then - # RET=1 - # fi + if [ $? -ne "0" ]; then + RET=1 + fi # # Series docstrings # pytest --doctest-modules -v \ From 6826dcf9b264a1d9559e711977c827bc9b26e87d Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Thu, 16 Aug 2018 11:38:11 +0200 Subject: [PATCH 15/20] add series + generic --- ci/doctests.sh | 19 +++++++++++++------ pandas/core/generic.py | 12 ++++++------ 2 files changed, 19 insertions(+), 12 deletions(-) diff --git a/ci/doctests.sh b/ci/doctests.sh index a337210837692..5f56b55e181f5 100755 --- a/ci/doctests.sh +++ b/ci/doctests.sh @@ -45,13 +45,20 @@ if [ "$DOCTEST" ]; then RET=1 fi - # # Series docstrings - # pytest --doctest-modules -v \ - # pandas/core/series.py -k"-agg -apply -map -nlargest -nonzero -nsmallest -reindex -replace -searchsorted -to_dict -to_excel" + # Series docstrings + pytest --doctest-modules -v pandas/core/series.py \ + -k"-agg -map -nlargest -nonzero -nsmallest -reindex -searchsorted -to_dict" - # if [ $? -ne "0" ]; then - # RET=1 - # fi + if [ $? -ne "0" ]; then + RET=1 + fi + + pytest --doctest-modules -v pandas/core/generic.py \ + -k"-_set_axis_name -_xs -droplevel -groupby -interpolate -pct_change -pipe -reindex -reindex_axis -resample -sample -to_json -to_xarray -transform -transpose -values" + + if [ $? -ne "0" ]; then + RET=1 + fi else echo "NOT running doctests" diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 2245abd780edd..fd372ce2fd78e 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -738,14 +738,14 @@ def droplevel(self, level, axis=0): Examples -------- >>> df = pd.DataFrame([ - ...: [1, 2, 3, 4], - ...: [5, 6, 7, 8], - ...: [9, 10, 11, 12] - ...: ]).set_index([0, 1]).rename_axis(['a', 'b']) + ... [1, 2, 3, 4], + ... [5, 6, 7, 8], + ... [9, 10, 11, 12] + ... ]).set_index([0, 1]).rename_axis(['a', 'b']) >>> df.columns = pd.MultiIndex.from_tuples([ - ...: ('c', 'e'), ('d', 'f') - ...:], names=['level_1', 'level_2']) + ... ('c', 'e'), ('d', 'f') + ... ], names=['level_1', 'level_2']) >>> df level_1 c d From c03c8953d0c44189c3a2bedd2102b0419d73635b Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Thu, 16 Aug 2018 12:12:59 +0200 Subject: [PATCH 16/20] also skip xs --- ci/doctests.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ci/doctests.sh b/ci/doctests.sh index 5f56b55e181f5..fed6056bceacf 100755 --- a/ci/doctests.sh +++ b/ci/doctests.sh @@ -54,7 +54,7 @@ if [ "$DOCTEST" ]; then fi pytest --doctest-modules -v pandas/core/generic.py \ - -k"-_set_axis_name -_xs -droplevel -groupby -interpolate -pct_change -pipe -reindex -reindex_axis -resample -sample -to_json -to_xarray -transform -transpose -values" + -k"-_set_axis_name -_xs -droplevel -groupby -interpolate -pct_change -pipe -reindex -reindex_axis -resample -sample -to_json -to_xarray -transform -transpose -values -xs" if [ $? -ne "0" ]; then RET=1 From d3d5a50d62197bf2908e81a936ac48440772bc43 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Thu, 16 Aug 2018 12:18:40 +0200 Subject: [PATCH 17/20] clean-up --- ci/doctests.sh | 37 +++++++++++++++---------------------- 1 file changed, 15 insertions(+), 22 deletions(-) diff --git a/ci/doctests.sh b/ci/doctests.sh index fed6056bceacf..065f9780e5ac7 100755 --- a/ci/doctests.sh +++ b/ci/doctests.sh @@ -12,32 +12,14 @@ if [ "$DOCTEST" ]; then echo "Running doctests" - # pytest --doctest-modules --ignore=pandas/tests -v pandas/core/frame.py + # running all doctests is not yet working + # pytest --doctest-modules --ignore=pandas/tests -v pandas # if [ $? -ne "0" ]; then # RET=1 # fi - - # # top-level reshaping functions - # pytest --doctest-modules -v \ - # pandas/core/reshape/concat.py \ - # pandas/core/reshape/pivot.py \ - # pandas/core/reshape/reshape.py \ - # pandas/core/reshape/tile.py - - # if [ $? -ne "0" ]; then - # RET=1 - # fi - - # # top-level io functionality - # pytest --doctest-modules -v pandas/io/* -k "read_" - - # if [ $? -ne "0" ]; then - # RET=1 - # fi - - # DataFrame docstrings + # DataFrame / Series docstrings pytest --doctest-modules -v pandas/core/frame.py \ -k"-assign -axes -combine -isin -itertuples -join -nlargest -nsmallest -nunique -pivot_table -quantile -query -reindex -reindex_axis -replace -round -set_index -stack -to_dict -to_records -to_stata -transform" @@ -45,7 +27,6 @@ if [ "$DOCTEST" ]; then RET=1 fi - # Series docstrings pytest --doctest-modules -v pandas/core/series.py \ -k"-agg -map -nlargest -nonzero -nsmallest -reindex -searchsorted -to_dict" @@ -60,6 +41,18 @@ if [ "$DOCTEST" ]; then RET=1 fi + # top-level reshaping functions + pytest --doctest-modules -v \ + pandas/core/reshape/concat.py \ + pandas/core/reshape/pivot.py \ + pandas/core/reshape/reshape.py \ + pandas/core/reshape/tile.py \ + -k"-crosstab -pivot_table -cut" + + if [ $? -ne "0" ]; then + RET=1 + fi + else echo "NOT running doctests" fi From 4884f03390e635bb5a0c4ed20b56d69345b48102 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Thu, 16 Aug 2018 14:06:12 +0200 Subject: [PATCH 18/20] add short docs about testing/validating docstrings --- doc/source/contributing.rst | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index ff06d024740bf..f452fa8af5726 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -365,6 +365,31 @@ This will identify methods documented in ``doc/source/api.rst`` that are not act class methods, and existing methods that are not documented in ``doc/source/api.rst``. +Updating a *pandas* docstring +----------------------------- + +When improving a single function or method's docstring, it is not necessarily +needed to build to full documentation (see next section). +However, there is a script that checks a docstring (for example for the ``DataFrame.mean`` method):: + + python scripts/validate_docstrings.py pandas.DataFrame.mean + +This script will indicate some formatting errors if present, and will also +run and test the examples included in the docstring. +Check the :ref:`pandas docstring guide ` for a detailed guide +on how to format the docstring. + +The examples in the docstring ('doctests') must be valid Python code, +that in a deterministic way returns the presented output, and that can be +copied and run by users. This can be checked with the script above, and is +also tested on Travis. A failing doctest will be a blocker for merging a PR. +Check the :ref:`examples ` section in the docstring guide +for some tips and tricks to get the doctests passing. + +When doing a PR with a docstring update, it is good to post the +output of the validation script in a comment on github. + + How to build the *pandas* documentation --------------------------------------- From caa43f1b3ee4416015afa0aecbb547b45ac3d5ad Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Thu, 16 Aug 2018 14:33:22 +0200 Subject: [PATCH 19/20] typo --- doc/source/contributing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index f452fa8af5726..f3880902d744d 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -369,7 +369,7 @@ Updating a *pandas* docstring ----------------------------- When improving a single function or method's docstring, it is not necessarily -needed to build to full documentation (see next section). +needed to build the full documentation (see next section). However, there is a script that checks a docstring (for example for the ``DataFrame.mean`` method):: python scripts/validate_docstrings.py pandas.DataFrame.mean From 25bc1581978a29d3a3e8dbad1d3c68ee28efce1e Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Thu, 16 Aug 2018 21:55:45 +0200 Subject: [PATCH 20/20] skip describe --- ci/doctests.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ci/doctests.sh b/ci/doctests.sh index 065f9780e5ac7..04b3e14a7120a 100755 --- a/ci/doctests.sh +++ b/ci/doctests.sh @@ -35,7 +35,7 @@ if [ "$DOCTEST" ]; then fi pytest --doctest-modules -v pandas/core/generic.py \ - -k"-_set_axis_name -_xs -droplevel -groupby -interpolate -pct_change -pipe -reindex -reindex_axis -resample -sample -to_json -to_xarray -transform -transpose -values -xs" + -k"-_set_axis_name -_xs -describe -droplevel -groupby -interpolate -pct_change -pipe -reindex -reindex_axis -resample -sample -to_json -to_xarray -transform -transpose -values -xs" if [ $? -ne "0" ]; then RET=1